Migrar da API SOAP do Ad Manager

A API SOAP do Ad Manager é uma API legada para ler e gravar dados do Ad Manager e gerar relatórios. Se você puder migrar, recomendamos usar a API 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 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 fazer a autenticação com a API Ad Manager (Beta), você pode usar as credenciais da API SOAP do Ad Manager ou criar novas. Com qualquer uma das opções, primeiro ative a API Ad Manager no seu projeto do Google Cloud. Para mais detalhes, consulte Autenticação.

Se você estiver usando uma biblioteca de cliente, configure as credenciais padrão do aplicativo 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 formato a seguir e defina a variável de ambiente como 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 do cliente novo ou atual.
  • CLIENT_SECRET: seu segredo do cliente novo ou atual.

  • 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 de filtro

A linguagem de consulta da API Ad Manager (Beta) oferece suporte a todos os recursos da linguagem de consulta do editor (PQL, na sigla em inglês), mas há diferenças significativas na sintaxe.

Este exemplo de listagem de objetos Order ilustra as principais mudanças, como a remoção de variáveis de vinculação, operadores que diferenciam maiúsculas de minúsculas e a substituição das 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 por 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) oferece suporte a todos os recursos da PQL, com as seguintes diferenças de sintaxe da API SOAP do Ad Manager:

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

    Usar operadores em letras maiúsculas

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

    Letras minúsculas tratadas como literais

    // 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 oferece suporte ao 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 dos campos 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 Ad Manager (Beta) não oferece suporte a variáveis de vinculação. Todos os valores precisam ser incorporados.

  • Os literais de string que contêm espaços precisam estar entre aspas duplas, por exemplo, "Foo bar". Não é possível usar aspas simples para incluir 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 deslocamentos para tokens de paginação

A API 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 de lista 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 Ad Manager (Beta) pode retornar menos resultados do que o tamanho da página solicitada, mesmo que haja outras 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 multithreading, use o token de paginação da primeira página para garantir que você esteja lendo o 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 Relatórios descontinuada. Por outro lado, a API REST só pode ler, gravar e gerar relatórios interativos.

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

Se você estiver usando SavedQuery, poderá migrar o relatório para um relatório interativo na interface e criar um mapeamento entre os dois espaços de ID. Para mais informações sobre como migrar relatórios na interface, consulte Migrar relatórios para relatórios interativos.

Para um mapeamento completo dos valores de enumeração SOAP para REST, consulte Referência de relatórios.

Entender as diferenças da API

Há algumas diferenças na forma como a API SOAP e a API REST processam definições e resultados de relatórios:

  • A API SOAP 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 à 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 Dimension valor de enumeração. As dimensões ENUM são enums abertos. É necessário processar valores de enumeração 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 são divididas 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 apenas como uma dimensão ao calcular o limite.