Cette API est disponible en version bêta. La documentation de l'API SOAP Ad Manager est disponible sur cette page.

Cette page a été traduite par l'API Cloud Translation.

Migrer depuis l'API SOAP Ad Manager

L'ancienne API SOAP Ad Manager permet de lire et d'écrire vos données Ad Manager, et d'exécuter des rapports. Si vous pouvez effectuer la migration, nous vous recommandons d'utiliser l'API Ad Manager (bêta). Toutefois, les versions de l'API SOAP Ad Manager sont compatibles avec leur cycle de vie habituel. Pour en savoir plus, consultez le calendrier d'abandon de l'API SOAP Ad Manager.

Le guide suivant décrit les différences entre l'API SOAP Ad Manager et l'API Ad Manager (bêta).

Apprendre

Les méthodes de service de l'API SOAP Ad Manager standard ont des concepts équivalents dans l'API Ad Manager. L'API Ad Manager propose également des méthodes permettant de lire des entités uniques. Le tableau suivant présente un exemple de mappage pour les méthodes Order:

Méthode SOAP	Méthodes REST
`getOrdersByStatement`	`networks.orders.get` `networks.orders.list`

Authentifier

Pour vous authentifier avec l'API Ad Manager (bêta), vous pouvez utiliser vos identifiants API SOAP Ad Manager existants ou en créer de nouveaux. Dans les deux cas, vous devez d'abord activer l'API Ad Manager dans votre projet Google Cloud. Pour en savoir plus, consultez la section Authentification.

Si vous utilisez une bibliothèque cliente, configurez les identifiants par défaut de l'application en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin d'accès à votre fichier de clé de compte de service. Pour en savoir plus, consultez la section Fonctionnement des identifiants par défaut de l'application.

Si vous utilisez des identifiants d'application installée, créez un fichier JSON au format suivant et définissez plutôt la variable d'environnement sur son chemin d'accès:

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

Remplacez les valeurs suivantes :

CLIENT_ID: votre nouvel ID client ou celui que vous possédez déjà.
CLIENT_SECRET: votre secret client nouveau ou existant.
REFRESH_TOKEN: votre jeton de rafraîchissement nouveau ou existant.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Comprendre les différences entre les filtres

Le langage de requête de l'API Ad Manager (bêta) est compatible avec toutes les fonctionnalités du langage de requête de l'éditeur (PQL, Publisher Query Language), mais il existe des différences de syntaxe importantes.

Cet exemple de liste d'objets Order illustre les principales modifications, telles que la suppression des variables de liaison, des opérateurs sensibles à la casse et le remplacement des clauses ORDER BY et LIMIT par des champs distincts:

API SOAP 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 (bêta)

Format JSON

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

Encodé en URL

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

L'API Ad Manager (bêta) est compatible avec toutes les fonctionnalités PQL, avec les différences de syntaxe suivantes par rapport à l'API SOAP Ad Manager:

Les opérateurs AND et OR sont sensibles à la casse dans l'API Ad Manager (bêta). Les valeurs and et or en minuscules sont traitées comme des chaînes de recherche littérales brutes, une fonctionnalité de l'API Ad Manager (bêta) permettant de rechercher dans plusieurs champs.

Utiliser des opérateurs en majuscules
```
// Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false
```
Minuscules traitées comme littérales
```
// 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
```
Le caractère * est un caractère générique pour la correspondance de chaînes. L'API Ad Manager (bêta) n'est pas compatible avec l'opérateur like.

PQL de l'API SOAP Ad Manager
```
// Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"
```
API Ad Manager (bêta)
```
// Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"
```
Les noms de champ doivent apparaître à gauche d'un opérateur de comparaison:

Filtre valide
```
updateTime > "2024-01-01T00:00:00Z"
```
Filtre non valide
```
"2024-01-01T00:00:00Z" < updateTime
```
L'API Ad Manager (bêta) n'est pas compatible avec les variables de liaison. Toutes les valeurs doivent être intégrées.
Les littéraux de chaîne contenant des espaces doivent être placés entre guillemets doubles, par exemple "Foo bar". Vous ne pouvez pas utiliser de guillemets simples pour encapsuler des littéraux de chaîne.

Supprimer les clauses de tri

La spécification d'un ordre de tri est facultative dans l'API Ad Manager (bêta). Si vous souhaitez spécifier un ordre de tri pour votre ensemble de résultats, supprimez la clause ORDER BY PQL et définissez plutôt le champ orderBy:

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

Passer des décalages aux jetons de pagination

L'API Ad Manager (bêta) utilise des jetons de pagination au lieu de clauses LIMIT et OFFSET pour parcourir de grands ensembles de résultats.

L'API Ad Manager (bêta) utilise un paramètre pageSize pour contrôler la taille de la page. Contrairement à la clause LIMIT de l'API SOAP Ad Manager, l'omission d'une taille de page ne renvoie pas l'ensemble de résultats complet. À la place, la méthode de liste utilise une taille de page par défaut de 50. L'exemple suivant définit pageSize et pageToken comme paramètres d'URL:

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

Contrairement à l'API SOAP Ad Manager, l'API Ad Manager (bêta) peut renvoyer moins de résultats que la taille de page demandée, même si des pages supplémentaires sont disponibles. Utilisez le champ nextPageToken pour déterminer s'il existe d'autres résultats.

Bien qu'un décalage ne soit pas obligatoire pour la pagination, vous pouvez utiliser le champ skip pour le multithreading. En multithreading, utilisez le jeton de pagination de la première page pour vous assurer que vous lisez à partir du même ensemble de résultats:

# 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