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 for possível migrar, recomendamos usar a API Ad Manager (Beta). No entanto, as versões da API SOAP do Ad Manager têm suporte ao ciclo de vida normal. 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 fazer a autenticação com a API Ad Manager (Beta), use suas credenciais da API SOAP do Ad Manager ou crie novas. Em qualquer uma das opções, primeiro é necessário ativar 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 abaixo e defina a variável de ambiente como o caminho:

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

Substitua os seguintes valores:

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

  • REFRESH_TOKEN: o 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 os filtros

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 sensíveis a maiú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"
}

URL codificado

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 do 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 Ad Manager (Beta). and e or em letras minúsculas são tratados como strings de pesquisa literais, um recurso na API Ad Manager (Beta) para pesquisar em vários campos.

    Usar operadores em 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 é 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 de ordenação

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 do 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 conjuntos grandes 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 do Ad Manager (Beta) pode retornar menos resultados do que o tamanho da página solicitado, mesmo que haja outras páginas. Use o campo nextPageToken para determinar se há outros resultados.

Embora um deslocamento não seja necessário para a paginação, é possível 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