API-Aufrufstruktur

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

Wenn Sie eine Clientbibliothek verwenden, um mit der API zu interagieren, brauchen Sie sich nicht um die zugrunde liegenden Anfragedetails zu kümmern. Beim Testen und Debuggen kann es jedoch nützlich sein, ein wenig über diese Tools zu wissen.

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

1. [Preferred] Erstellen Sie den Text der Anfrage als Protokollpuffer, senden Sie ihn über HTTP/2 an den Server, deserialisieren Sie die Antwort in einen Protokollpuffer und interpretieren Sie die Ergebnisse. Der größte Teil unserer Dokumentation beschreibt die Verwendung von gRPC.

2. [Optional] Erstellen Sie den Anfragetext als JSON-Objekt, senden Sie ihn über HTTP 1.1 an den Server, deserialisieren Sie die Antwort als JSON-Objekt und interpretieren Sie die Ergebnisse. Weitere Informationen zur Verwendung von REST finden Sie im Leitfaden zur REST-Benutzeroberfläche.

Hinweis: In diesem Leitfaden werden die Struktur- und Transport-Header beschrieben, die sowohl für gRPC- als auch für REST-Protokolle gemein sind.

Ressourcennamen

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

Wichtiger Hinweis :In der Ressourcendokumentation finden Sie alle unterstützten Ressourcen und ihre Pfaddarstellung (resource_name). Dasselbe Format wird auch für andere Dienste verwendet.

Zusammengesetzte IDs

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

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

• AdGroupId von 123 + ~ + AdGroupAdId von 45678 = Anzeigen-ID der zusammengesetzten Anzeigengruppe von 123~45678.

Anfrageheader

Dies sind die HTTP-Header (oder gRPC-Metadaten), die im Text der Anfrage enthalten sind:

Autorisierung

Sie müssen ein OAuth2-Zugriffstoken im Format Authorization: Bearer YOUR_ACCESS_TOKEN hinzufügen. Dieses dient dazu, entweder ein Verwaltungskonto, das im Auftrag eines Kunden handelt, oder einen Werbetreibenden zu identifizieren, der sein eigenes Konto direkt verwaltet. Eine Anleitung zum Abrufen eines Zugriffstokens finden Sie im OAuth2-Leitfaden. Ein Zugriffstoken ist nach Erhalt eine Stunde lang gültig. Aktualisieren Sie es nach Ablauf, um ein neues zu erhalten. Hinweis: Abgelaufene Tokens werden von unseren Clientbibliotheken automatisch aktualisiert.

Entwickler-Token

Ein Entwickler-Token ist eine 22-stellige Zeichenfolge, die einen Google Ads API-Entwickler eindeutig identifiziert. Ein Beispiel für einen Entwickler-Token-String ist ABcdeFGH93KL-NOPQ_STUv. Das Entwicklertoken muss das Format developer-token : ABcdeFGH93KL-NOPQ_STUv haben.

login-customer-id

Dies ist die Kundennummer des autorisierten Kunden, der in der Anfrage verwendet werden soll, ohne Bindestriche (-). Wenn Sie über ein Verwaltungskonto auf das Kundenkonto zugreifen, ist dieser Header erforderlich und auf die Kundennummer des Verwaltungskontos festgelegt.

Wichtiger Begriff: Der ausführende Kunde ist die Kundennummer in der Nutzlast der Anfrage. Der ausführende Kunde in der folgenden CampaignBudgetService-Anfrage ist beispielsweise 1234567890:

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

Das Festlegen von login-customer-id entspricht der Auswahl eines Kontos in der Google Ads-Benutzeroberfläche, nachdem Sie sich angemeldet oder oben rechts auf Ihr Profilbild geklickt haben. Wenn Sie diesen Header nicht einfügen, wird standardmäßig der Betriebskunde verwendet.

Hinweis :Sie können die Liste der Konten abrufen, auf die mit Ihren OAuth-Anmeldedaten direkt zugegriffen werden kann. Senden Sie dazu eine CustomerService.ListAccessibleCustomers-Anfrage. Der login-customer-id ist für diesen Anfragetyp nicht erforderlich und hat keine Auswirkungen auf die Liste der zurückgegebenen Kunden.

verknüpfte Kundennummer

Dieser Header wird von Drittanbietern von App-Analysetools nur verwendet, wenn sie Conversions in ein verknüpftes Google Ads-Konto hochladen.

Stellen wir uns ein Szenario vor, in dem Nutzer des Kontos A dem Konto B über eine ThirdPartyAppAnalyticsLink Lese- und Bearbeitungszugriff auf seine Entitäten gewähren. Nach der Verknüpfung kann ein Nutzer des Kontos B im Rahmen der über den Link bereitgestellten Berechtigungen API-Aufrufe für das Konto A ausführen. In diesem Fall werden die API-Aufrufberechtigungen für das Konto A durch die Drittanbieterverknüpfung zum Konto B und nicht durch die Verwaltungskontobeziehung bestimmt, die in anderen API-Aufrufen verwendet wird.

Der Drittanbieter des App-Analysetools führt einen API-Aufruf wie folgt aus:

• linked-customer-id: Das Konto des App-Analysetools eines Drittanbieters, über das die Daten hochgeladen werden (Konto B).
• customer-id: Das Google Ads-Konto, in das Daten hochgeladen werden (Konto A).
• login-customer-id- und Authorization-Header: eine Kombination von Werten zur Identifizierung eines Nutzers, der Zugriff auf das Konto B hat.

Antwortheader

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

request-id

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