API-Aufrufstruktur

In diesem Leitfaden 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. Einige Kenntnisse über die Struktur von API-Aufrufen können jedoch beim Testen und Debuggen nützlich 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.

Bevorzugt:

  1. Erstellen Sie den Text der Anfrage als Protocol Buffer.
  2. Senden Sie ihn über HTTP/2 an den Server.
  3. Deserialisieren Sie die Antwort in einen Protocol Buffer.
  4. Interpretieren Sie die Ergebnisse.

In den meisten Dokumentationen wird die Verwendung von gRPC beschrieben.

Optional:

  1. Erstellen Sie den Text der Anfrage 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 im Leitfaden zur REST-Schnittstelle.

Ressourcenkennungen

Objekte in der Google Ads API werden mit strukturierten Ressourcennamen und zusammengesetzten Kennungen adressiert.

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.

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.

Eine AdGroupAd hat beispielsweise das Ressourcennamenmuster customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Da die zusammengesetzte Kennung die ID der übergeordneten Anzeigengruppe (ad_group.id) und die zugrunde liegende Anzeigen-ID (ad_group_ad.ad.id) kombiniert, wird die Anzeigengruppen-ID vor die Anzeigen-ID gestellt:

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

Anfrageheader

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

Autorisierung

Sie müssen ein OAuth 2.0-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 im OAuth2-Leitfaden. Ein Zugriffstoken ist eine Stunde nach dem Abrufen gültig. Wenn es abläuft, aktualisieren Sie es, 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 ausreichende Berechtigungen haben. Ein USER_PERMISSION_DENIED-Fehler gibt an, dass der authentifizierte Nutzer möglicherweise keinen Zugriff auf das in der Anfrage angegebene Kundenkonto hat. Wenn Ihr Google Cloud-Projekt nur für den Test-Zugriff genehmigt wurde und Sie eine Anfrage an ein Produktionskonto senden, gibt die API in Version 25 und höher AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION zurück (oder AuthorizationError.ACTION_NOT_PERMITTED in Version 24 und früher). Weitere Informationen zum Verwalten von Berechtigungen finden Sie unter Zugriffsebenen in Google Ads.

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 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 beheben. Eine detaillierte Erläuterung, wie der Kontozugriff aufgelöst wird, finden Sie im Leitfaden zum OAuth Zugriffsmodell.

https://googleads.googleapis.com/v26/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 rechts oben. 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. 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 durch den API-Aufruf verwaltet oder aktualisiert wird. Die ID des Werbetreibendenkontos wird in der Anfrage angegeben. In REST ist dies der Pfad-Parameter 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 Produkt Verknüpfung mit dem Partner hat, wodurch der Partner Zugriff auf den Werbetreibenden erhält.

Ein Nutzer mit Zugriff auf das Partnerkonto sendet API-Aufrufe, um Aktionen für Entitäten im Werbetreibendenkonto auszuführen (z. B. Conversions hochladen oder Nutzerlisten verwalten). Das verknüpfte Konto kann das Werbetreibendenkonto selbst oder ein Verwaltungskonto des Werbetreibendenkontos sein.

Die Anfrageheader müssen so festgelegt werden:

  • Authorization: Ein OAuth 2.0-Zugriffstoken für einen Nutzer mit Zugriff auf das Partnerkonto.
  • login-customer-id: Die Kundennummer des Partnerkontos. 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 das Werbetreibendenkonto eine direkte Produktverknüpfung mit dem Partnerkonto hat, ist das verknüpfte Konto das Werbetreibendenkonto und linked-customer-id muss auf die Kundennummer des Werbetreibendenkontos festgelegt werden.
  • Wenn das Werbetreibendenkonto von einem Verwaltungskonto verwaltet wird, das eine Produktverknüpfung mit dem Partnerkonto 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 das Werbetreibendenkonto 1111111111 eine direkte Verknüpfung mit dem Partner konto 2222222222 hat und der API-Aufruf auf customers/1111111111/... abzielt:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Beispiel 2: Verknüpfung über ein Verwaltungskonto

Wenn das Werbetreibendenkonto 1111111111 vom Verwaltungskonto 3333333333 verwaltet wird, das Verwaltungskonto 3333333333 eine Verknüpfung mit dem Partner konto 2222222222 hat und der API-Aufruf auf customers/1111111111/... abzielt:

Authorization: Bearer YOUR_ACCESS_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. Geben Sie diesen Wert an, wenn Sie sich an den Support wenden, um Fehler bei fehlgeschlagenen oder unerwarteten API-Anfragen zu beheben.

Zurück
Ressourcenmetadaten