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, Aufrufe an die API zu senden.

Empfohlen:

  1. Erstellen Sie den Anfragetext als Protokollpuffer.

  2. Senden Sie ihn über HTTP/2 an den Server.

  3. Deserialisieren Sie die Antwort in einen Protokollpuffer.

  4. Interpretieren Sie die Ergebnisse.

In den meisten Dokumentationen wird die Verwendung von gRPC beschrieben.

Optional:

  1. Erstellen Sie den Anfragetext als ein JSON-Objekt.

  2. Senden Sie ihn über HTTP 1.1 an den Server.

  3. Deserialisieren Sie die Antwort als JSON-Objekt.

  4. Interpretieren Sie die Ergebnisse.

Weitere Informationen zur Verwendung von REST finden Sie in der Anleitung 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 finden Sie unter Ressourcennamen der REST Schnittstelle.

resource_name

Zusammengesetzte IDs

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

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

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

Anfrageheader

Das sind die HTTP-Header (oder gRPC Metadaten), die den Text in der Anfrage begleiten:

Autorisierung

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

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

developer-token

Ein Entwicklertoken ist ein String mit 22 Zeichen, der 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 Kundennummer 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 Kundennummer des Verwaltungskontos festgelegt werden. Wenn Sie login-customer-id bei der Authentifizierung über ein Verwaltungskonto nicht angeben, führt dies zu einem AuthorizationError.USER_PERMISSION_DENIED-Fehler. Weitere Informationen zu diesem Fehlertyp finden Sie unter Häufige Fehler. Eine detaillierte Erläuterung zur Auflösung des Kontozugriffs finden Sie in der Anleitung zum OAuth-Zugriffsmodell.

https://googleads.googleapis.com/v25/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 ausführende Kunde verwendet.

linked-customer-id

Dieser Header ist erforderlich und wird von Partnern (z. B. Drittanbieter-App-Analysetools oder Datenpartnern) verwendet, wenn sie in einem verknüpften Google Ads-Konto agieren. In diesem Header muss die Kundennummer des Google Ads-Kontos angegeben werden, das die Produktverknüpfung enthält.

Nehmen wir an, ein Partner muss API-Aufrufe an ein Google Ads-Konto senden, das auf einer Produktverknüpfung basiert.

  • 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 von App-Analysen oder ein Datenpartner).
  • Verknüpftes Konto: Das Google Ads-Konto, das eine etablierte Produktverknüpfung mit dem Partner hat, wodurch der Partner Zugriff auf den Werbetreibenden erhält.

Ein Nutzer mit Zugriff auf den Partner sendet API-Aufrufe, um Aktionen für Entitäten im Konto des Werbetreibenden auszuführen (z. B. Conversions hochladen oder Nutzerlisten verwalten). 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 mit Zugriff auf den Partner.
  • 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 basiert.

Es gibt zwei Verknüpfungsszenarien:

  • Wenn der Werbetreibende eine direkte Produktverknüpfung mit dem Partner hat, ist das verknüpfte Konto der Werbetreibende und linked-customer-id muss auf die Kundennummer des Werbetreibenden festgelegt werden.
  • Wenn der Werbetreibende von einem Verwaltungskonto verwaltet wird, das eine Produktverknüpfung mit dem Partner hat, ist das verknüpfte Konto das Verwaltungskonto und linked-customer-id muss auf die Kundennummer des Verwaltungskontos festgelegt werden.

Beispiel 1: Direkte Verknüpfung

Wenn der Werbetreibende 1111111111 eine direkte Verknüpfung mit dem 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: Verknüpfung über ein Verwaltungskonto

Wenn der Werbetreibende 1111111111 von dem Verwaltungskonto 3333333333 verwaltet wird, das Verwaltungskonto 3333333333 eine Verknüpfung mit dem 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: 3333333333

Antwortheader

Die folgenden Header (oder gRPC Trailing-Metadaten) werden mit dem Antworttext zurückgegeben. Wir empfehlen, diese Werte zu protokollieren, um Fehler zu beheben.

request-id

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

Zurück
Ressourcenmetadaten