Von der Ad Manager SOAP API migrieren

Die Ad Manager SOAP API ist eine Legacy-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). Die Versionen der Ad Manager SOAP API werden jedoch für ihren typischen Lebenszyklus unterstützt. Weitere Informationen finden Sie im Zeitplan für die Einstellung der Ad Manager SOAP API Deprecation Schedule.

In dieser 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. In der folgenden Tabelle sehen Sie eine Beispielzuordnung für Order-Methoden:

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

Authentifizieren

Zur Authentifizierung mit der Ad Manager API (Beta) können Sie Ihre vorhandenen Anmeldedaten für die Ad Manager SOAP API verwenden oder neue erstellen. In beiden Fällen 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 stattdessen eine JSON-Datei im folgenden Format und legen Sie die Umgebungsvariable 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 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 Publisher Query Language (PQL)-Funktionen, 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 Bind-Variablen, die Unterscheidung zwischen Groß- und 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, wobei sich die Syntax von der Ad Manager SOAP API in folgenden Punkten unterscheidet:

  • Bei den Operatoren AND und OR wird in der Ad Manager API (Beta) zwischen Groß- und Kleinschreibung unterschieden. Die Kleinbuchstaben and und or werden als reine literale Suchstrings behandelt. Mit dieser Funktion in der Ad Manager API (Beta) können Sie in allen Feldern suchen.

    Operatoren in Großbuchstaben verwenden

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

    Kleinbuchstaben als Literal behandeln

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

    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 von 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 Bind-Variablen. Alle Werte müssen inline sein.

  • Stringliterale mit Leerzeichen 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 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 Offsets zu Paginierungstokens migrieren

In der Ad Manager API (Beta) werden Paginierungstokens anstelle von LIMIT- und OFFSET-Klauseln verwendet, um große Ergebnismengen zu durchlaufen.

In der Ad Manager API (Beta) wird die Seitengröße mit dem Parameter pageSize gesteuert. Im Gegensatz zur LIMIT-Klausel in der Ad Manager SOAP API wird bei Weglassen der Seitengröße nicht die gesamte Ergebnismenge zurückgegeben. Stattdessen wird für die 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 gibt die Ad Manager API (Beta) möglicherweise weniger Ergebnisse als die angeforderte Seitengröße zurück, auch wenn weitere Seiten vorhanden sind. Verwenden Sie das Feld nextPageToken, um festzustellen, ob weitere Ergebnisse vorhanden sind.

Ein Offset ist für die Paginierung nicht erforderlich, Sie können jedoch das Feld skip für Multithreading verwenden. Verwenden Sie beim Multithreading das Paginierungstoken von der ersten Seite, um sicherzustellen, dass Sie aus derselben Ergebnismenge 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

Mit der SOAP API können Berichte nur im eingestellten Berichtstool gelesen und ausgeführt werden. Mit der REST API können interaktive Berichte hingegen nur gelesen, geschrieben und ausgeführt werden.

Die Berichtstools und APIs haben unterschiedliche ID-Bereiche. Die ID einer 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 interaktiven Berichten migrieren.

Unterschiede bei APIs

Es gibt einige Unterschiede in der Art und Weise, wie die SOAP API und die REST API Berichtsdefinitionen und -ergebnisse verarbeiten:

  • Die SOAP API hat den Ergebnissen automatisch eine entsprechende ID-Dimension hinzugefügt, wenn in einem Bericht nur NAME angefordert wurde. In der REST API müssen Sie die Dimension ID explizit zu ReportDefinition hinzufügen, damit sie in den Ergebnissen enthalten ist.

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

  • Die SOAP API hat zwischen Dimensions und DimensionAttributes unterschieden. Die REST API hat ein einheitliches Dimension-Enum, das beide enthält.

  • Die SOAP API hatte 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 ORDER_NAME, ORDER_ID und ORDER_START_DATE einbeziehen, wird bei der Berechnung des Limits nur eine Dimension gezählt.