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. 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 Anfragetext 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 Text der Anfrage 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.

Ressourcenkennungen

Auf Objekte in der Google Ads API wird über strukturierte Ressourcennamen und zusammengesetzte Kennungen zugegriffen.

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 in der REST-Schnittstelle unter Ressourcennamen.

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 Ressourcenname-Muster customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Da der zusammengesetzte Identifier die ID der übergeordneten Anzeigengruppe (ad_group.id) und die zugrunde liegende Anzeigen-ID (ad_group_ad.ad.id) kombiniert, stellen wir die Anzeigengruppen-ID der Anzeigen-ID voran:

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

Anfrageheader

Dies sind die HTTP-Header (oder gRPC-Metadaten), die den Textkörper 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 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: 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 weist darauf hin, dass der authentifizierte Nutzer möglicherweise keinen Zugriff auf das im Antrag 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 niedriger). 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 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 detaillierte Erläuterung dazu, wie der Kontozugriff aufgelöst wird, finden Sie im Leitfaden 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 rechts oben. Wenn Sie diesen Header nicht angeben, wird standardmäßig der betreibende 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 für ein Google Ads-Konto basierend auf einer Produktverknüpfung ausführen.

• 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 Pfad-Parameter 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, das eine Produktverknüpfung mit dem Partner hat und dem Partner Zugriff auf den Werbetreibenden gewährt.

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

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 Kunden-ID des Werbetreibendenkontos festgelegt werden.
• Wenn das Advertiser-Konto von einem Verwaltungskonto verwaltet wird, das eine Produktverknüpfung mit dem Partner-Konto hat, ist das Linked account das Verwaltungskonto und linked-customer-id muss auf die Kunden-ID des Verwaltungskontos festgelegt werden.

Beispiel 1: Direkter Link

Wenn das Werbetreibendenkonto 1111111111 eine direkte Verknüpfung mit dem Partnerkonto 2222222222 hat und der API-Aufruf auf customers/1111111111/... ausgerichtet ist:

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

Beispiel 2: Verwaltungskontolink

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/... ausgerichtet ist:

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.