Para analizar nuestros productos y proporcionar comentarios sobre ellos, únete al canal oficial de Ad Manager en Discord, en el servidor Google Advertising and Measurement Community.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Cómo migrar desde la API de SOAP de Ad Manager

La API de SOAP de Ad Manager es una API heredada para leer y escribir tus datos de Ad Manager, y ejecutar informes. Si puedes migrar, te recomendamos que uses la API de Ad Manager (beta). Sin embargo, las versiones de la API de SOAP de Ad Manager son compatibles con su ciclo de vida típico. Para obtener más información, consulta el Programa de baja de la API de SOAP de Ad Manager .

En la siguiente guía, se describen las diferencias entre la API de SOAP de Ad Manager y la API de Ad Manager (beta).

Obtener información

Los métodos de servicio estándar de la API de SOAP de Ad Manager tienen conceptos equivalentes en la API de Ad Manager. La API de Ad Manager también tiene métodos para leer entidades individuales. En la siguiente tabla, se muestra un ejemplo de asignación para los métodos Order:

Método de SOAP	Métodos de REST
`getOrdersByStatement`	`networks.orders.get` `networks.orders.list`

Autenticar

Para autenticarte con la API de Ad Manager (beta), puedes usar tus credenciales existentes de la API de SOAP de Ad Manager o crear credenciales nuevas. Con cualquiera de las opciones, primero debes habilitar la API de Ad Manager en tu proyecto de Google Cloud. Para obtener más detalles, consulta Autenticación.

Si usas una biblioteca cliente, configura las credenciales predeterminadas de la aplicación. Para ello, establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso del archivo de claves de tu cuenta de servicio. Para obtener más detalles, consulta Cómo funcionan las credenciales predeterminadas de la aplicación.

Si usas credenciales de la aplicación instalada, crea un archivo JSON con el siguiente formato y establece la variable de entorno en su ruta de acceso:

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

Reemplaza los siguientes valores:

CLIENT_ID: Es tu ID de cliente nuevo o existente.
CLIENT_SECRET: Es tu secreto de cliente nuevo o existente.
REFRESH_TOKEN: Es tu token de actualización nuevo o existente.

Linux o macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Comprende las diferencias en los filtros

El lenguaje de consulta de la API de Ad Manager (beta) admite todas las funciones del lenguaje de consulta del publicador (PQL), pero existen diferencias significativas en la sintaxis.

En este ejemplo para enumerar objetos Order, se ilustran los cambios principales, como la eliminación de variables de vinculación, los operadores que distinguen mayúsculas de minúsculas y el reemplazo de las cláusulas ORDER BY y LIMIT por campos separados:

API de SOAP de Ad Manager

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

API de Ad Manager (beta)

Formato JSON

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

URL codificada

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

La API de Ad Manager (beta) admite todas las capacidades de PQL, con las siguientes diferencias de sintaxis con respecto a la API de SOAP de Ad Manager:

Los operadores AND y OR distinguen mayúsculas de minúsculas en la API de Ad Manager (beta). Las letras and y or en minúscula se tratan como cadenas de búsqueda literales sin formato, una función de la API de Ad Manager (beta) para buscar en los campos.

Usa operadores en mayúscula
```
// Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false
```
Las letras en minúscula se tratan como literales
```
// Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false
```

El carácter * es un comodín para la coincidencia de cadenas. La API de Ad Manager (beta) no admite el operador like.

PQL de la API de SOAP de Ad Manager

// Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

API de Ad Manager (beta)

// Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

Los nombres de los campos deben aparecer en el lado izquierdo de un operador de comparación:

Filtro válido
```
updateTime > "2024-01-01T00:00:00Z"
```
Filtro no válido
```
"2024-01-01T00:00:00Z" < updateTime
```
La API de Ad Manager (beta) no admite variables de vinculación. Todos los valores deben estar intercalados.
Los literales de cadena que contienen espacios deben estar entre comillas dobles, por ejemplo, "Foo bar". No puedes usar comillas simples para encerrar literales de cadena.

Quita las cláusulas order by

Especificar un orden de clasificación es opcional en la API de Ad Manager (beta). Si deseas especificar un orden de clasificación para tu conjunto de resultados, quita la cláusula ORDER BY de PQL y establece el campo orderBy en su lugar:

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

Migra de desplazamientos a tokens de paginación

La API de Ad Manager (beta) usa tokens de paginación en lugar de cláusulas LIMIT y OFFSET para paginar grandes conjuntos de resultados.

La API de Ad Manager (beta) usa un parámetro pageSize para controlar el tamaño de la página. A diferencia de la cláusula LIMIT en la API de SOAP de Ad Manager, si se omite un tamaño de página, no se muestra todo el conjunto de resultados. En su lugar, el método de lista usa un tamaño de página predeterminado de 50. En el siguiente ejemplo, se establecen pageSize y pageToken como parámetros de URL:

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

A diferencia de la API de SOAP de Ad Manager, la API de Ad Manager (beta) puede mostrar menos resultados que el tamaño de página solicitado, incluso si hay páginas adicionales. Usa el campo nextPageToken para determinar si hay resultados adicionales.

Si bien no se requiere un desplazamiento para la paginación, puedes usar el campo skip para subprocesos múltiples. Cuando uses subprocesos múltiples, usa el token de paginación de la primera página para asegurarte de leer del mismo conjunto de resultados:

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50

Migra informes

La API de SOAP solo puede leer y ejecutar informes en la herramienta Informes obsoleta. Por el contrario, la API de REST solo puede leer, escribir y ejecutar informes interactivos.

Las herramientas y las APIs de informes tienen un espacio de ID diferente. El ID de un SavedQuery en la API de SOAP no se puede usar en la API de REST.

Si usas SavedQuery, puedes migrar el informe a un informe interactivo en la IU y crear una asignación entre los dos espacios de ID. Para obtener más información sobre la migración de informes, consulta Cómo migrar informes a informes interactivos.

Comprende las diferencias de la API

Existen algunas diferencias en la forma en que la API de SOAP y la API de REST controlan las definiciones y los resultados de los informes:

La API de SOAP agregaba automáticamente una dimensión ID correspondiente a los resultados cuando un informe solo solicitaba el NAME. En la API de REST, debes agregar explícitamente la dimensión ID a la ReportDefinition para que se incluya en los resultados.
La API de SOAP no tenía tipos explícitos para las métricas. La API de REST define un tipo de datos, que se documenta en el Dimension valor de enumeración. Ten en cuenta que las dimensiones ENUM son enumeraciones abiertas. Debes controlar los valores de enumeración nuevos y desconocidos cuando analices los resultados.
La API de SOAP separó Dimensions y DimensionAttributes. La API de REST tiene una enumeración Dimension unificada que contiene ambos.
La API de SOAP no tenía un límite en la cantidad de dimensiones. Los informes interactivos tienen un límite de 10 dimensiones en la IU y la API. Las dimensiones que se desglosan por el mismo espacio de ID se consideran una sola dimensión. Por ejemplo, incluir ORDER_NAME, ORDER_ID y ORDER_START_DATE solo cuenta como 1 dimensión cuando se calcula el límite.