API-Aufrufstruktur

In dieser Anleitung wird die allgemeine Struktur aller API-Aufrufe beschrieben.

Wenn Sie eine Clientbibliothek verwenden, um mit der API zu interagieren, müssen Sie die zugrunde liegenden Anfragedetails nicht kennen. Ein gewisses Wissen über die Struktur von API-Aufrufen kann jedoch beim Testen und Debuggen hilfreich sein.

Die Google Ads API ist eine gRPC API mit REST-Bindungen. Das bedeutet, dass es zwei Möglichkeiten gibt, die API aufzurufen.

Bevorzugt:

  1. Erstellen Sie den Text der Anfrage als Protokollpuffer.

  2. Senden Sie sie mit HTTP/2 an den Server.

  3. Deserialisieren Sie die Antwort in einen Protokollpuffer.

  4. Ergebnisse interpretieren:

In den meisten unserer Dokumentationen wird die Verwendung von gRPC beschrieben.

Optional:

  1. Erstellen Sie den Anfragetext als JSON-Objekt.

  2. Senden Sie sie mit HTTP 1.1 an den Server.

  3. Deserialisieren Sie die Antwort als JSON-Objekt.

  4. Ergebnisse interpretieren:

Weitere Informationen zur Verwendung von REST finden Sie im Leitfaden zur REST-Schnittstelle.

Ressourcennamen

Die meisten Objekte in der API werden durch ihre Ressourcennamenstrings identifiziert. Diese Strings dienen auch als URLs, wenn die REST-Schnittstelle verwendet wird. Die Struktur der Ressourcennamen finden Sie in der REST-Schnittstelle unter Resource Names.

Zusammengesetzte IDs

Wenn die ID eines Objekts nicht global eindeutig ist, wird eine zusammengesetzte ID für dieses Objekt erstellt, indem die übergeordnete ID und eine Tilde (~) vorangestellt werden.

Da die Anzeigen-ID einer Anzeigengruppe beispielsweise nicht global eindeutig ist, wird ihr die ID des übergeordneten Objekts (Anzeigengruppe) vorangestellt, um eine eindeutige zusammengesetzte ID zu erstellen:

  • AdGroupId von 123 + ~ + AdGroupAdId von 45678 = zusammengesetzte Anzeigengruppen-ID von 123~45678.

Anfrageheader

Dies sind die HTTP-Header (oder gRPC-Metadaten), die dem Text in der Anfrage beigefügt sind:

Autorisierung

Sie müssen ein OAuth2-Zugriffstoken in Form von Authorization: Bearer YOUR_ACCESS_TOKEN angeben, das entweder ein Verwaltungskonto identifiziert, das im Namen eines Kunden agiert, oder einen Werbetreibenden, der sein eigenes Konto direkt verwaltet. Eine Anleitung zum Abrufen eines Zugriffstokens finden Sie im OAuth2-Leitfaden. Ein Zugriffstoken ist eine Stunde lang gültig. Wenn es abläuft, müssen Sie es aktualisieren, um ein neues zu erhalten. Hinweis: Unsere Clientbibliotheken aktualisieren abgelaufene Tokens automatisch.

Wenn Autorisierungsfehler auftreten, prüfen Sie, ob Sie die richtigen Anmeldedaten verwenden und über ausreichende Berechtigungen verfügen. Ein USER_PERMISSION_DENIED-Fehler weist darauf hin, dass der authentifizierte Nutzer möglicherweise keinen Zugriff auf das im Antrag angegebene Kundenkonto hat. Weitere Informationen zum Verwalten von Berechtigungen finden Sie unter Google Ads-Zugriffsebenen.

developer-token

Ein Entwicklertoken ist eine 22 Zeichen lange Zeichenfolge, die einen Google Ads API-Entwickler eindeutig identifiziert. Ein Beispiel für einen Entwicklertoken-String ist ABcdeFGH93KL-NOPQ_STUv. Das Entwicklertoken sollte im Format developer-token : ABcdeFGH93KL-NOPQ_STUv angegeben werden.

login-customer-id

Dies ist die Kunden-ID des autorisierten Kunden, die in der Anfrage verwendet werden soll, ohne Bindestriche (-). Wenn Sie über ein Verwaltungskonto auf das Kundenkonto zugreifen, ist dieser Header erforderlich und muss auf die Kunden-ID des Verwaltungskontos festgelegt werden. Wenn Sie login-customer-id nicht angeben, wenn Sie sich über ein Verwaltungskonto authentifizieren, führt dies zu einem AuthorizationError.USER_PERMISSION_DENIED-Fehler. Weitere Informationen zu diesem Fehlertyp finden Sie unter Häufige Fehler.

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

Das Festlegen von login-customer-id entspricht der Auswahl eines Kontos in der Google Ads-Benutzeroberfläche nach der Anmeldung oder dem Klicken auf Ihr Profilbild oben rechts. Wenn Sie diesen Header nicht angeben, wird standardmäßig der operierende Kunde verwendet.

linked-customer-id

Dieser Header ist erforderlich und wird von Partnern (z. B. Drittanbietern von App-Analysetools oder Datenpartnern) verwendet, wenn sie auf ein verknüpftes Google Ads-Konto zugreifen. In diesem Header muss die Kundennummer des Google Ads-Kontos mit der Produktverknüpfung angegeben werden.

Stellen Sie sich vor, ein Partner muss API-Aufrufe an ein Google Ads-Konto basierend auf einer Produktverknüpfung senden.

  • Werbetreibender: Das Google Ads-Konto, das vom API-Aufruf verwaltet oder aktualisiert wird. Die ID des Werbetreibendenkontos wird in der Anfrage angegeben. In REST ist dies der Pfadparameter customerId (z. B. customers/1111111111/...) und in gRPC das Feld customer_id in der Anfrage.
  • Partner: Das Partnerkonto, z. B. ein Drittanbieter für App-Analysen oder ein Datenpartner.
  • Verknüpftes Konto: Das Google Ads-Konto, für das eine Produktverknüpfung mit dem Partner eingerichtet wurde, wodurch der Partner Zugriff auf den Werbetreibenden erhält.

Ein Nutzer mit Zugriff auf Partner führt API-Aufrufe aus, um Aktionen für Einheiten in Advertiser auszuführen (z. B. zum Hochladen von Conversions oder zum Verwalten von Nutzerlisten). Das verknüpfte Konto kann das Konto des Werbetreibenden selbst oder ein Verwaltungskonto des Werbetreibenden sein.

Die Anfrageheader müssen so festgelegt werden:

  • Authorization: Ein OAuth2-Token für einen Nutzer, der Zugriff auf Partner hat.
  • developer-token: Das Entwicklertoken für die API-Anwendung, das in der Regel mit dem Partner verknüpft ist.
  • login-customer-id: Die Kundennummer des Partners. Der authentifizierte Nutzer muss Zugriff auf dieses Konto haben.
  • linked-customer-id: Die Kundennummer des verknüpften Kontos. Dieser Header signalisiert, dass die Autorisierung für diese Anfrage auf der Produktverknüpfung des verknüpften Kontos mit dem Partner beruht.

Es gibt zwei Verknüpfungsszenarien:

  • Wenn der Werbetreibende eine direkte Produktverknüpfung mit dem Partner hat, ist „Verknüpftes Konto“ der Werbetreibende und linked-customer-id muss auf die Kundennummer des Werbetreibenden festgelegt werden.
  • Wenn der Werbetreibende über ein Verwaltungskonto verwaltet wird, das eine Produktverknüpfung mit dem Partner hat, ist „Linked account“ das Verwaltungskonto und linked-customer-id muss auf die Kunden-ID des Verwaltungskontos festgelegt werden.

Beispiel 1: Direkter Link

Wenn Werbetreibender 1111111111 eine direkte Verbindung zu Partner 2222222222 hat und der API-Aufruf auf customers/1111111111/... ausgerichtet ist:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Beispiel 2: Manager-Link

Wenn der Werbetreibende 1111111111 von der Verwaltungs-ID 3333333333 verwaltet wird, die Verwaltungs-ID 3333333333 mit dem Partner 2222222222 verknüpft ist und der API-Aufruf auf customers/1111111111/... ausgerichtet ist:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Antwortheader

Die folgenden Header (oder grpc-Trailing-Metadata) werden mit dem Antworttext zurückgegeben. Wir empfehlen, diese Werte zu Debugging-Zwecken zu protokollieren.

request-id

request-id ist ein String, der diese Anfrage eindeutig identifiziert.

Zurück
Ressourcenmetadaten