Von der Ad Manager SOAP API migrieren

Die Ad Manager SOAP API ist eine alte API zum Lesen und Schreiben von Ad Manager-Daten und zum Ausführen von Berichten. Wenn Sie migrieren können, empfehlen wir die Verwendung der Ad Manager API (Beta). Ad Manager SOAP API-Versionen werden jedoch für ihren üblichen Lebenszyklus unterstützt. Weitere Informationen finden Sie im Zeitplan für die Einstellung der Ad Manager SOAP API.

In der folgenden Anleitung werden die Unterschiede zwischen der Ad Manager SOAP API und der Ad Manager API (Beta) beschrieben.

Lernen

Die Standarddienstmethoden der Ad Manager SOAP API haben entsprechende Konzepte in der Ad Manager API. Die Ad Manager API bietet auch Methoden zum Lesen einzelner Entitäten. Die folgende Tabelle zeigt eine Beispielzuordnung für Order-Methoden:

SOAP-Methode REST-Methoden
getOrdersByStatement networks.orders.get
networks.orders.list

Authentifizieren

Sie können sich mit Ihren vorhandenen Anmeldedaten für die Ad Manager SOAP API oder mit neuen Anmeldedaten bei der Ad Manager API (Beta) authentifizieren. Bei beiden Optionen müssen Sie zuerst die Ad Manager API in Ihrem Google Cloud-Projekt aktivieren. Weitere Informationen finden Sie unter Authentifizierung.

Wenn Sie eine Clientbibliothek verwenden, richten Sie Standardanmeldedaten für Anwendungen ein, indem Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad Ihrer Dienstkonto-Schlüsseldatei festlegen. Weitere Informationen finden Sie unter Funktionsweise von Standardanmeldedaten für Anwendungen.

Wenn Sie Anmeldedaten für installierte Anwendungen verwenden, erstellen Sie eine JSON-Datei im folgenden Format und legen Sie die Umgebungsvariable stattdessen auf den Pfad fest:

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

Ersetzen Sie die folgenden Werte:

  • CLIENT_ID: Ihre neue oder vorhandene Client-ID.
  • CLIENT_SECRET: Ihr neues oder vorhandenes Clientsecret.

  • REFRESH_TOKEN: Ihr neues oder vorhandenes Aktualisierungstoken.

Linux oder macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Unterschiede bei den Filtern

Die Abfragesprache der Ad Manager API (Beta) unterstützt alle Funktionen der Publisher Query Language (PQL). Es gibt jedoch erhebliche Unterschiede bei der Syntax.

In diesem Beispiel für die Auflistung von Order-Objekten werden die wichtigsten Änderungen veranschaulicht, z. B. das Entfernen von Bindvariablen, die Entfernung von buchstabensensitiven Operatoren und das Ersetzen von ORDER BY- und LIMIT-Klauseln durch separate Felder:

Ad Manager SOAP API 

<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>

Ad Manager API (Beta)

JSON-Format

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

URL-codiert

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

Die Ad Manager API (Beta) unterstützt alle PQL-Funktionen. Die Syntax unterscheidet sich jedoch von der der Ad Manager SOAP API:

  • Bei den Operatoren AND und OR wird in der Ad Manager API (Beta) zwischen Groß- und Kleinschreibung unterschieden. Kleingeschriebene and und or werden als reine Suchstrings behandelt. Das ist eine Funktion in der Ad Manager API (Beta), mit der Sie in mehreren Feldern suchen können.

    Operatoren in Großbuchstaben verwenden

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

    Kleinbuchstaben werden als Literal behandelt

    // 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

  • Das Zeichen * ist ein Platzhalter für die Stringübereinstimmung. Der Operator like wird von der Ad Manager API (Beta) nicht unterstützt.

    Ad Manager SOAP API PQL

    // Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

    Ad Manager API (Beta)

    // Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

  • Feldnamen müssen links neben einem Vergleichsoperator stehen:

    Gültiger Filter

    updateTime > "2024-01-01T00:00:00Z"

    Ungültiger Filter

    "2024-01-01T00:00:00Z" < updateTime

  • Die Ad Manager API (Beta) unterstützt keine Bindevariablen. Alle Werte müssen eingefügt werden.

  • Stringliterale, die Leerzeichen enthalten, müssen in doppelte Anführungszeichen gesetzt werden, z. B. "Foo bar". Sie können keine einfachen Anführungszeichen verwenden, um Stringliterale einzufügen.

Sortierungsklauseln entfernen

In der Ad Manager API (Beta) ist die Angabe einer Sortierreihenfolge optional. Wenn Sie eine Sortierreihenfolge für die Ergebnismenge angeben möchten, entfernen Sie die PQL-Klausel ORDER BY und legen Sie stattdessen das Feld orderBy fest:

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

Von Offset- zu Paginierungs-Token migrieren

Die Ad Manager API (Beta) verwendet Paginierungstokens anstelle von LIMIT- und OFFSET-Klauseln, um große Ergebnismengen zu durchsuchen.

In der Ad Manager API (Beta) wird die Seitengröße über den Parameter pageSize gesteuert. Im Gegensatz zur LIMIT-Klausel in der Ad Manager SOAP API wird bei Auslassung einer Seitengröße nicht die gesamte Ergebnismenge zurückgegeben. Stattdessen verwendet die Liste die Standardseitengröße 50. Im folgenden Beispiel werden pageSize und pageToken als URL-Parameter festgelegt:

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

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

Im Gegensatz zur Ad Manager SOAP API gibt die Ad Manager API (Beta) möglicherweise weniger Ergebnisse als die angeforderte Seitengröße zurück, auch wenn es weitere Seiten gibt. Verwenden Sie das Feld nextPageToken, um festzustellen, ob weitere Ergebnisse vorhanden sind.

Für die Paginierung ist zwar kein Offset erforderlich, Sie können das Feld skip aber für Multithreading verwenden. Verwenden Sie beim Multithreading das Paginierungstoken der ersten Seite, um sicherzustellen, dass Sie aus demselben Ergebnissatz lesen:

# 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