Von der Ad Manager SOAP API migrieren

Die Ad Manager SOAP API ist eine alte API zum Lesen und Schreiben Ihrer 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 während ihres typischen 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 Standardmethoden 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 ein Beispiel für die Zuordnung für Order-Methoden:

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

Authentifizieren

Zur Authentifizierung bei der Ad Manager API (Beta) können Sie Ihre vorhandenen Ad Manager SOAP API-Anmeldedaten verwenden oder neue erstellen. 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 die 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 ihren 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 Client-Secret.

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

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

Dieses Beispiel für das Auflisten von Order-Objekten veranschaulicht die wichtigsten Änderungen, z. B. das Entfernen von Bindungsvariablen, die Berücksichtigung der Groß-/Kleinschreibung bei 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. Es gibt jedoch die folgenden Syntaxunterschiede zur Ad Manager SOAP API:

  • Bei den Operatoren AND und OR wird in der Ad Manager API (Beta) zwischen Groß- und Kleinschreibung unterschieden. Klein geschriebene and und or werden als einfache Literal-Suchstrings behandelt. Das ist eine Funktion in der Ad Manager API (Beta), mit der in Feldern gesucht werden kann.

    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 den Stringvergleich. Die Ad Manager API (Beta) unterstützt den Operator like nicht.

    PQL für die Ad Manager SOAP API

    // 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 auf der linken Seite eines Vergleichsoperators 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 Bindungsvariablen. Alle Werte müssen inline sein.

  • 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 einzuschließen.

„ORDER BY“-Klauseln entfernen

Die Angabe einer Sortierreihenfolge ist in der Ad Manager API (Beta) optional. Wenn Sie eine Sortierreihenfolge für Ihre 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 Offsets zu Paginierungs-Tokens migrieren

Bei der Ad Manager API (Beta) werden zum Durchsuchen großer Ergebnissätze Paginierungstokens anstelle von LIMIT- und OFFSET-Klauseln verwendet.

In der Ad Manager API (Beta) wird die Seitengröße mit dem Parameter pageSize gesteuert. Anders als bei der LIMIT-Klausel in der Ad Manager SOAP API wird beim Weglassen einer Seitengröße nicht die gesamte Ergebnismenge zurückgegeben. Stattdessen wird bei der Listenmethode eine Standardseitengröße von 50 verwendet. 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 kann die Ad Manager API (Beta) weniger Ergebnisse als die angeforderte Seitengröße zurückgeben, auch wenn es zusätzliche Seiten gibt. Verwenden Sie das Feld nextPageToken, um festzustellen, ob weitere Ergebnisse vorhanden sind.

Ein Offset ist für die Paginierung nicht erforderlich, Sie können das Feld skip jedoch für Multithreading verwenden. Verwenden Sie beim Multithreading das Paginierungstoken von 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

Berichte migrieren

Über die SOAP API können nur Berichte im eingestellten Berichte-Tool gelesen und ausgeführt werden. Umgekehrt kann die REST API nur interaktive Berichte lesen, schreiben und ausführen.

Für die Berichterstellungstools und APIs wird ein anderer ID-Bereich verwendet. Die ID eines SavedQuery in der SOAP API kann nicht in der REST API verwendet werden.

Wenn Sie SavedQuery verwenden, können Sie den Bericht in der Benutzeroberfläche zu einem interaktiven Bericht migrieren und eine Zuordnung zwischen den beiden ID-Bereichen erstellen. Weitere Informationen zum Migrieren von Berichten finden Sie unter Berichte zu „Interaktive Berichte“ migrieren.

API-Unterschiede verstehen

Es gibt einige Unterschiede zwischen der SOAP API und der REST API in Bezug auf die Verarbeitung von Berichtsdefinitionen und ‑ergebnissen:

  • Über die SOAP API wurde den Ergebnissen automatisch eine entsprechende ID-Dimension hinzugefügt, wenn in einem Bericht nur die NAME angefordert wurde. In der REST API müssen Sie die Dimension ID explizit dem ReportDefinition hinzufügen, damit sie in die Ergebnisse aufgenommen wird.

  • In der SOAP API gab es keine expliziten Typen für Messwerte. Die REST API definiert einen Datentyp, der im Enum-Wert Dimension dokumentiert ist. ENUM-Dimensionen sind offene Enums. Sie müssen neue und unbekannte Enum-Werte beim Parsen von Ergebnissen verarbeiten.

  • In der SOAP API wurden Dimensions und DimensionAttributes getrennt. Die REST API hat ein einheitliches Dimension-Enum, das beide enthält.

  • In der SOAP API gab es kein Limit für die Anzahl der Dimensionen. Für interaktive Berichte gilt sowohl in der Benutzeroberfläche als auch in der API ein Limit von 10 Dimensionen. Dimensionen, die nach demselben ID-Bereich aufgeschlüsselt werden, werden als eine Dimension gezählt. Wenn Sie beispielsweise nur ORDER_NAME, ORDER_ID und ORDER_START_DATE einbeziehen, wird dies bei der Berechnung des Limits als eine Dimension gezählt.