API-Aufrufstruktur

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

Wenn Sie eine Clientbibliothek für die Interaktion mit der API verwenden, müssen Sie sich keine Gedanken über die zugrunde liegenden Anfragedetails machen. Beim Testen und Debuggen kann es sich jedoch als nützlich erweisen, ein wenig über sie 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 an einen Protokollzwischenspeicher 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 in der Anleitung zur REST-Oberflä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. 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.

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

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

Anfrageheader

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

Autorisierung

Sie müssen ein OAuth2-Zugriffstoken in Form von Authorization: Bearer YOUR_ACCESS_TOKEN einfügen. Es identifiziert entweder ein Verwaltungskonto, das im Namen eines Kunden handelt, oder einen Werbetreibenden, der sein eigenes Konto direkt verwaltet. Eine Anleitung zum Abrufen von Zugriffstokens finden Sie im OAuth2-Leitfaden. Ein Zugriffstoken ist nach Erhalt eine Stunde lang gültig. Aktualisieren Sie das Zugriffstoken nach Ablauf, um ein neues abzurufen. Beachten Sie, dass unsere Clientbibliotheken abgelaufene Tokens automatisch aktualisieren.

Entwicklertoken

Das Entwickler-Token ist eine 22 Zeichen lange 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, die in der Anfrage verwendet werden soll, ohne Bindestriche (-). Wenn Ihr Zugriff auf das Kundenkonto über ein Verwaltungskonto erfolgt, ist dieser Header erforderlich und muss auf die Kundennummer des Verwaltungskontos festgelegt werden.

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

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

verknüpfte-Kundennummer

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

Stellen Sie sich ein Szenario vor, bei dem Nutzer im Konto A über eine ThirdPartyAppAnalyticsLink Lese- und Bearbeitungszugriff auf die zugehörigen Entitäten für das Konto B gewähren. Nach der Verknüpfung kann ein Nutzer des Kontos B vorbehaltlich der über die Verknüpfung bereitgestellten Berechtigungen API-Aufrufe für das Konto A senden. In diesem Fall werden die API-Aufrufberechtigungen für das Konto A durch die Drittanbieterverknüpfung zum Konto B und nicht über die Verwaltungskonto-Beziehung, die in anderen API-Aufrufen verwendet wird, bestimmt.

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

• linked-customer-id: Das App-Analysekonto des 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 fronting-metadata) werden mit dem Antworttext zurückgegeben. Wir empfehlen, diese Werte zu Zwecken der Fehlerbehebung zu protokollieren.

request-id

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