Migrer depuis l'API SOAP Ad Manager

L'API SOAP Ad Manager est une ancienne API permettant de lire et d'écrire vos données Ad Manager, et de générer des rapports. Si vous le pouvez, 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 standards de l'API SOAP Ad Manager ont des concepts équivalents dans l'API Ad Manager. L'API Ad Manager dispose également de 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 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. 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 au fichier de clé de votre compte de service. Pour en savoir plus, consultez la page 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: votre secret client nouveau ou existant.

  • REFRESH_TOKEN: votre 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é 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 opérateurs and et or en minuscules sont traités comme des chaînes de recherche littérales simples, une fonctionnalité de l'API Ad Manager (bêta) permettant d'effectuer des recherches dans les 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 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 placer des littéraux de chaîne.

Supprimer les clauses "order by"

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 PQL ORDER BY et définissez plutôt le champ orderBy :

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

Migrer des décalages vers des 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 des résultats. 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 des résultats supplémentaires.

Bien qu'un décalage ne soit pas requis pour la pagination, vous pouvez utiliser le champ skip pour le multithreading. Lors du multithreading, utilisez le jeton de pagination de la première page pour vous assurer que vous lisez le 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 lire et exécuter des rapports que dans l'outil Rapports obsolète. À l'inverse, l'API REST ne peut lire, écrire et exécuter que des rapports interactifs.

Les outils et API de création de rapports ont un espace d'ID différent. L'ID d'une 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'interface utilisateur et créer un mappage entre les deux espaces d'ID. Pour en savoir plus sur la migration des rapports, consultez Migrer des rapports vers des rapports interactifs.

Comprendre les différences entre les API

Il existe des différences dans 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 le NAME. Dans l'API REST, vous devez ajouter explicitement la dimension ID à la 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 Dimension valeur d'énumération. Notez que les dimensions ENUM sont des énumérations ouvertes. Vous devez gérer les valeurs d'énumération nouvelles et inconnues lors de l'analyse des résultats.

  • L'API SOAP séparait les Dimensions et les DimensionAttributes. L'API REST dispose d'une énumération Dimension unifiée qui contient les deux.

  • L'API SOAP ne limitait pas le nombre de dimensions. Les rapports interactifs sont limités à 10 dimensions dans l'interface utilisateur et l'API. Les dimensions qui sont ventilées par 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 n'est comptabilisée que comme une seule dimension lors du calcul de la limite.