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 se admiten durante 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 Ad Manager (beta) y la API de Ad Manager SOAP.

Obtener información

Los métodos de servicio estándar de la API de Ad Manager SOAP 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 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 Ad Manager SOAP 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 estableciendo la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso a tu archivo de claves de la cuenta de servicio. Para obtener más detalles, consulta Cómo funcionan las credenciales predeterminadas de la aplicación.

Si usas credenciales de aplicación instalada, crea un archivo JSON con el siguiente formato y configura 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: 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 consultas de la API de Ad Manager (beta) admite todas las funciones del lenguaje de consultas 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 las 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"
}

Codificado con URL

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 funciones de PQL, con las siguientes diferencias de sintaxis con respecto a la API de Ad Manager SOAP:

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

    Usa operadores en mayúsculas

    // 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.

    Lenguaje de consultas de la API de Ad Manager SOAP

    // 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 de ordenamiento

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 configura 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 las cláusulas LIMIT y OFFSET para desplazarse por 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, omitir un tamaño de página no devuelve el conjunto de resultados completo. En su lugar, el método list 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 Ad Manager SOAP, la API de Ad Manager (beta) puede devolver 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 que estás leyendo el 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 que dejó de estar disponible. 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 objeto 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 entre las APIs

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 agregó automáticamente una dimensión ID correspondiente a los resultados cuando un informe solo solicitó la dimensión NAME. En la API de REST, debes agregar explícitamente la dimensión ID al objeto 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 valor de enumeración Dimension. Ten en cuenta que las dimensiones de ENUM son enums abiertos. 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 un enum Dimension unificado 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 tanto en la IU como en la API. Las dimensiones que se desglosan según 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.