Migrar da API SOAP do Ad Manager

A API SOAP do Ad Manager é uma API legada para leitura e gravação dos dados do Ad Manager e execução de relatórios. Se você puder migrar, recomendamos usar a API do Ad Manager (Beta). No entanto, as versões da API SOAP do Ad Manager são compatíveis com o ciclo de vida típico delas. Para mais informações, consulte a programação de descontinuação da API SOAP do Ad Manager.

O guia a seguir descreve as diferenças entre a API SOAP do Ad Manager e a API do Ad Manager (Beta).

Aprender

Os métodos de serviço padrão da API SOAP do Ad Manager têm conceitos equivalentes na API Ad Manager. A API Ad Manager também tem métodos para ler entidades únicas. A tabela a seguir mostra um exemplo de mapeamento para métodos Order:

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

Autenticar

Para autenticar com a API Ad Manager (Beta), use suas credenciais atuais da API SOAP do Ad Manager ou crie novas. Com qualquer uma das opções, primeiro ative a API Ad Manager no projeto do Google Cloud. Para mais detalhes, consulte Autenticação.

Se você estiver usando uma biblioteca de cliente, configure o Application Default Credentials definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo de chave da conta de serviço. Para mais detalhes, consulte Como o Application Default Credentials funciona.

Se você estiver usando credenciais de aplicativo instalado, crie um arquivo JSON no seguinte formato e defina a variável de ambiente para o caminho dele:

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

Substitua os seguintes valores:

  • CLIENT_ID: seu ID de cliente novo ou atual.
  • CLIENT_SECRET: o novo ou atual segredo do cliente.

  • REFRESH_TOKEN: seu token de atualização novo ou atual.

Linux ou macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Entender as diferenças entre filtros

A linguagem de consulta da API Ad Manager (Beta) é compatível com todos os recursos da linguagem de consulta do editor (PQL), mas há diferenças significativas na sintaxe.

Este exemplo para listar objetos Order ilustra as principais mudanças, como a remoção de variáveis de vinculação, operadores sensíveis a maiúsculas e minúsculas e a substituição de cláusulas ORDER BY e LIMIT por campos separados:

API SOAP do 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 Ad Manager (Beta)

Formato JSON

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

Codificado para URL

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

A API Ad Manager (Beta) é compatível com todos os recursos da PQL, com as seguintes diferenças de sintaxe em relação à API SOAP do Ad Manager:

  • Os operadores AND e OR diferenciam maiúsculas de minúsculas na API do Ad Manager (Beta). As letras minúsculas and e or são tratadas como strings de pesquisa literal simples, um recurso da API do Ad Manager (Beta) para pesquisar em todos os campos.

    Usar operadores em maiúsculas

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false

    Minúsculas tratadas como literal

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

  • O caractere * é um curinga para correspondência de strings. A API Ad Manager (Beta) não é compatível com o operador like.

    PQL da API SOAP do Ad Manager

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

    API Ad Manager (Beta)

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

  • Os nomes de campo precisam aparecer no lado esquerdo de um operador de comparação:

    Filtro válido

    updateTime > "2024-01-01T00:00:00Z"

    Filtro inválido

    "2024-01-01T00:00:00Z" < updateTime

  • A API do Ad Manager (Beta) não é compatível com variáveis de vinculação. Todos os valores precisam ser inline.

  • Os literais de string que contêm espaços precisam ser colocados entre aspas duplas, por exemplo, "Foo bar". Não é possível usar aspas simples para envolver literais de string.

Remover cláusulas "ORDER BY"

Especificar uma ordem de classificação é opcional na API Ad Manager (Beta). Se você quiser especificar uma ordem de classificação para o conjunto de resultados, remova a cláusula ORDER BY da PQL e defina o campo orderBy:

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

Migrar de offsets para tokens de paginação

A API do Ad Manager (Beta) usa tokens de paginação em vez de cláusulas LIMIT e OFFSET para percorrer grandes conjuntos de resultados.

A API Ad Manager (Beta) usa um parâmetro pageSize para controlar o tamanho da página. Ao contrário da cláusula LIMIT na API SOAP do Ad Manager, omitir um tamanho de página não retorna todo o conjunto de resultados. Em vez disso, o método "list" usa um tamanho de página padrão de 50. O exemplo a seguir define pageSize e 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}

Ao contrário da API SOAP do Ad Manager, a API do Ad Manager (Beta) pode retornar menos resultados do que o tamanho da página solicitado, mesmo que haja mais páginas. Use o campo nextPageToken para determinar se há mais resultados.

Embora um deslocamento não seja necessário para a paginação, você pode usar o campo skip para multithreading. Ao usar várias linhas de execução, use o token de paginação da primeira página para garantir que você esteja lendo do mesmo 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

Migrar relatórios

A API SOAP só pode ler e gerar relatórios na ferramenta de relatórios descontinuada. Por outro lado, a API REST só pode ler, gravar e executar Relatórios interativos.

As ferramentas e APIs de relatórios têm um espaço de ID diferente. O ID de um SavedQuery na API SOAP não pode ser usado na API REST.

Se você estiver usando o SavedQuery, migre o relatório para um relatório interativo na interface e crie um mapeamento entre os dois espaços de ID. Para mais informações sobre a migração de relatórios, consulte Migrar relatórios para os Relatórios interativos.

Entender as diferenças entre as APIs

Há algumas diferenças entre como as APIs SOAP e REST processam definições e resultados de relatórios:

  • A SOAP API adicionava automaticamente uma dimensão ID correspondente aos resultados quando um relatório solicitava apenas o NAME. Na API REST, é necessário adicionar explicitamente a dimensão ID ao ReportDefinition para que ela seja incluída nos resultados.

  • A API SOAP não tinha tipos explícitos para métricas. A API REST define um tipo de dados, documentado no valor de enumeração Dimension. As dimensões ENUM são enums abertos. É necessário processar valores de enum novos e desconhecidos ao analisar os resultados.

  • A API SOAP separou Dimensions e DimensionAttributes. A API REST tem uma enumeração Dimension unificada que contém os dois.

  • A API SOAP não tinha um limite para o número de dimensões. Os relatórios interativos têm um limite de 10 dimensões na interface e na API. As dimensões que detalham pelo mesmo espaço de ID são contadas como uma única dimensão. Por exemplo, incluir ORDER_NAME, ORDER_ID e ORDER_START_DATE conta como uma dimensão ao calcular o limite.