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 realizar la migración, 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).

Más 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 SOAP Métodos 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 otras 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, configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso de 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 en 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: Tu secreto de cliente nuevo o existente

  • REFRESH_TOKEN: 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 entre 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 muestran los cambios más importantes, 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"
}

Codificación de 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 SOAP de Ad Manager:

  • Los operadores AND y OR distinguen mayúsculas de minúsculas en la API de Ad Manager (beta). and y or en minúsculas se consideran cadenas de búsqueda literales sin formato, una función de la API de Ad Manager (beta) para realizar búsquedas 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

    Minúsculas tratadas 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 unir cadenas literales.

Quita las cláusulas de orden

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

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

Migra de los offsets a los 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, omitir un tamaño de página no 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.

Aunque no se requiere un desplazamiento para la paginación, puedes usar el campo skip para la multitarea. Cuando uses varios subprocesos, usa el token de paginación de la primera página para asegurarte de leer desde 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