Pour discuter de nos produits et nous faire part de vos commentaires, rejoignez le canal Discord officiel Ad Manager sur le serveur de la communauté Google Advertising and Measurement.

Migrer depuis l'API SOAP Ad Manager

L'API Ad Manager SOAP est une ancienne API permettant de lire et d'écrire vos données Ad Manager, et d'exécuter des rapports. Si vous pouvez migrer, 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'arrêt 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 pour 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 auprès de l'API Ad Manager (bêta), vous pouvez utiliser vos identifiants existants de l'API SOAP Ad Manager ou en créer d'autres. Quelle que soit l'option choisie, 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 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 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 ID client nouveau ou existant.
CLIENT_SECRET : clé secrète du client (nouvelle ou existante).
REFRESH_TOKEN : jeton d'actualisation 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 pour les éditeurs (PQL), mais il existe des différences de syntaxe importantes.

Cet exemple de liste d'objets Order illustre les principaux changements, tels 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é au format 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 chaînes de recherche littérales brutes and et or en minuscules sont traitées comme des chaînes de recherche littérales brutes. Il s'agit d'une fonctionnalité de l'API Ad Manager (bêta) permettant de rechercher des 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 des littéraux
```
// 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 champs doivent figurer à 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 encadrer les littéraux de chaîne.

Supprimer les clauses "order by"

Il n'est pas obligatoire de spécifier un ordre de tri 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 PQL ORDER BY et définissez plutôt le champ orderBy :

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

Conseil : Alors que l'API Ad Manager SOAP recommande d'inclure systématiquement une clause ORDER BY pour assurer la cohérence de la pagination, l'API Ad Manager (bêta) maintient la cohérence avec les jetons de pagination.

Migrer des décalages vers les jetons de pagination

L'API Ad Manager (bêta) utilise des jetons de pagination au lieu des clauses LIMIT et OFFSET pour parcourir les 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 méthode list utilise plutôt 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 s'il existe des pages supplémentaires. Utilisez le champ nextPageToken pour déterminer s'il existe d'autres résultats.

Bien qu'un décalage ne soit pas requis pour la pagination, vous pouvez utiliser le champ skip pour le multithreading. Lorsque vous utilisez le multithreading, utilisez le jeton de pagination de la première page pour vous assurer de lire les données 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

Migrer des rapports

L'API SOAP ne peut que lire et exécuter des rapports dans l'outil Rapports obsolète. À l'inverse, l'API REST ne peut que lire, écrire et exécuter des rapports interactifs.

Les outils et API de création de rapports ont un espace d'ID différent. L'ID d'un SavedQuery dans l'API SOAP ne peut pas être utilisé dans l'API REST.

Si vous utilisez SavedQuery, vous pouvez migrer le rapport vers un rapport interactif dans l'UI et créer un mappage entre les deux espaces d'ID. Pour en savoir plus sur la migration de rapports, consultez Migrer des rapports vers Rapports interactifs.

Comprendre les différences entre les API

Il existe quelques différences entre la façon dont l'API SOAP et l'API REST gèrent les définitions et les résultats des rapports :

L'API SOAP ajoutait automatiquement une dimension ID correspondante aux résultats lorsqu'un rapport ne demandait que NAME. Dans l'API REST, vous devez ajouter explicitement la dimension ID à ReportDefinition pour qu'elle soit incluse dans les résultats.
L'API SOAP ne comportait pas de types explicites pour les métriques. L'API REST définit un type de données, documenté sur la valeur d'énumération Dimension. Notez que les dimensions ENUM sont des énums ouverts. Vous devez gérer les valeurs d'énumération nouvelles et inconnues lors de l'analyse des résultats.
L'API SOAP séparait Dimensions et DimensionAttributes. L'API REST dispose d'un enum Dimension unifié qui contient les deux.
L'API SOAP ne limitait pas le nombre de dimensions. Les rapports interactifs sont limités à 10 dimensions dans l'UI et l'API. Les dimensions qui se répartissent selon le même espace d'ID sont comptabilisées comme une seule dimension. Par exemple, l'inclusion de ORDER_NAME, ORDER_ID et ORDER_START_DATE ne compte que pour une seule dimension lors du calcul de la limite.

Migrer depuis l'API SOAP Ad Manager Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Apprendre

Authentifier

Linux ou macOS

Windows

Comprendre les différences entre les filtres

API SOAP Ad Manager

API Ad Manager (bêta)

Supprimer les clauses "order by"

Migrer des décalages vers les jetons de pagination

Migrer des rapports

Comprendre les différences entre les API

Migrer depuis l'API SOAP Ad Manager