API-Aufrufstruktur

In diesem Leitfaden wird die allgemeine Struktur aller API-Aufrufe beschrieben.

Wenn Sie eine Clientbibliothek für die Interaktion mit der API verwenden, müssen Sie die zugrunde liegenden Anfragedetails nicht kennen. Einige Kenntnisse über die Struktur von API-Aufrufen können jedoch beim Testen und Debuggen hilfreich sein.

Die Google Ads API ist eine gRPC API mit REST-Bindungen. Es gibt also zwei Möglichkeiten, die API aufzurufen.

Bevorzugt:

  1. Erstellen Sie den Text der Anfrage als Protokollzwischenspeicher.
  2. Senden Sie sie über HTTP/2 an den Server.
  3. Deserialisieren Sie die Antwort in einen Protokollzwischenspeicher.
  4. Ergebnisse interpretieren.

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

Optional:

  1. Erstellen Sie den Text der Anfrage als JSON-Objekt.
  2. Senden Sie sie über 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.

Ressourcenkennzeichnungen

Objekte in der Google Ads API werden über strukturierte Ressourcennamen und zusammengesetzte 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. Informationen zur 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 übergeordnete ID und eine Tilde (~) vorangestellt werden.

Ein 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 der Anzeigen-ID vorangestellt:

  • 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 in Form von Authorization: Bearer YOUR_ACCESS_TOKEN angeben, das entweder ein Verwaltungskonto, das im Namen eines Kunden handelt, oder einen Werbetreibenden, der sein eigenes Konto direkt verwaltet, identifiziert. Eine Anleitung zum Abrufen eines Zugriffstokens finden Sie im OAuth2-Leitfaden. Ein Zugriffstoken ist nach dem Erwerb eine Stunde lang gültig. Wenn es abläuft, aktualisieren Sie das Zugriffstoken, um ein neues abzurufen. Unsere Clientbibliotheken aktualisieren abgelaufene Tokens automatisch.

Wenn Autorisierungsfehler auftreten, prüfen Sie, ob Sie die richtigen Anmeldedaten verwenden und ausreichende Berechtigungen haben. Der Fehler USER_PERMISSION_DENIED weist darauf hin, 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 ist und Sie eine Anfrage an ein Produktionskonto senden, gibt die API in v25 und höher AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION (oder in v24 und früher AuthorizationError.ACTION_NOT_PERMITTED) zurück. Weitere Informationen zum Verwalten von Berechtigungen finden Sie unter Zugriffsebenen in Google Ads.

login-customer-id

Das ist die Kundennummer des autorisierten Kunden, die in der Anfrage ohne Bindestriche (-) verwendet werden soll. 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, wird der Fehler AuthorizationError.USER_PERMISSION_DENIED ausgegeben. Weitere Informationen zu diesem Fehlertyp finden Sie unter Häufige Fehler beheben. Eine ausführliche Erläuterung dazu, wie der Kontozugriff aufgelöst wird, finden Sie im Leitfaden zum OAuth-Zugriffsmodell.

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

Das Festlegen der 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. Drittanbietern von App-Analysetools oder Datenpartnern) verwendet, wenn sie Aktionen für ein verknüpftes Google Ads-Konto ausführen. In diesem Header muss die Kundennummer des Google Ads-Kontos mit der Produktverknüpfung angegeben werden.

Angenommen, ein Partner muss API-Aufrufe an ein Google Ads-Konto senden, das mit einem Produkt verknüpft ist.

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

Ein Nutzer mit Zugriff auf das Partnerkonto führt API-Aufrufe aus, um Aktionen für Entitäten im Werbetreibendenkonto auszuführen (z. B. um Conversions hochzuladen oder Nutzerlisten zu 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, der Zugriff auf den Partner hat.
  • 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: Direkter Link

Wenn das Werbetreibendenkonto 1111111111 direkt mit dem Partnerkonto 2222222222 verknüpft ist 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 mit Verwaltungskonto

Wenn das Werbetreibendenkonto 1111111111 vom Verwaltungskonto 3333333333 verwaltet wird, das Verwaltungskonto 3333333333 mit dem Partnerkonto 2222222222 verknüpft ist 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 Debugging-Zwecken zu protokollieren.

request-id

request-id ist ein String, der diese Anfrage eindeutig identifiziert. Geben Sie diesen Wert an, wenn Sie sich an den Support wenden, um fehlgeschlagene oder unerwartete API-Anfragen zu beheben.

Zurück
Ressourcenmetadaten