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.
[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.
[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.
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.
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
von123
+~
+AdGroupAdId
von45678
= Anzeigen-ID der zusammengesetzten Anzeigengruppe von123~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.
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.
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 (KontoB
).customer-id
: Das Google Ads-Konto, in das Daten hochgeladen werden (KontoA
).login-customer-id
- undAuthorization
-Header: eine Kombination von Werten zur Identifizierung eines Nutzers, der Zugriff auf das KontoB
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.