API-Aufrufstruktur

In dieser Anleitung 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. Für das Testen und Debuggen kann es jedoch hilfreich sein, die Struktur der API-Aufrufe zu kennen.

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

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

Hinweis :In dieser Anleitung werden die Struktur- und Transportheader beschrieben, die sowohl für gRPC- als auch für REST-Protokolle gelten.

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 der Ressourcennamen finden Sie in der REST-Schnittstelle unter Resource Names.

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 die übergeordnete ID und eine Tilde (~) vorangestellt werden.

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

• AdGroupId von 123 + ~ + AdGroupAdId von 45678 = zusammengesetzte Anzeigengruppen-Anzeigen-ID von 123~45678.

Anfrageheader

Dies sind die HTTP-Header (oder gRPC-Metadaten), die dem Text in der Anfrage beigefügt sind:

Autorisierung

Sie müssen ein OAuth2-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. Unsere Clientbibliotheken aktualisieren abgelaufene Tokens automatisch.

developer-token

Ein Entwicklertoken ist ein 22 Zeichen langer String, der einen Google Ads API-Entwickler eindeutig identifiziert. Ein Beispiel für einen Entwicklertoken-String ist ABcdeFGH93KL-NOPQ_STUv. Das Entwicklertoken sollte in Form von developer-token : ABcdeFGH93KL-NOPQ_STUv angegeben werden.

login-customer-id

Dies ist die Kunden-ID 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 Kunden-ID des Verwaltungskontos festgelegt werden.

Schlüsselbegriff :Der Betriebskunde ist die Kunden-ID in der Anfrage-Payload. Im folgenden CampaignBudgetService-Beispiel ist der Betriebskunde 1234567890:

https://googleads.googleapis.com/v20/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 oben rechts. Wenn Sie diesen Header nicht angeben, wird standardmäßig der operating customer verwendet.

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

linked-customer-id

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

Stellen Sie sich das Szenario vor, in dem Nutzer des Kontos A über eine ThirdPartyAppAnalyticsLink Lese- und Bearbeitungszugriff auf die zugehörigen Einheiten für das Konto B gewähren. Nach der Verknüpfung kann ein Nutzer des Kontos B API-Aufrufe für das Konto A ausführen, sofern die Berechtigungen der Verknüpfung dies zulassen. In diesem Fall werden die Berechtigungen für API-Aufrufe für das Konto A durch die Drittanbieterverknüpfung mit dem Konto B bestimmt und nicht durch die Beziehung zwischen dem Verwaltungskonto und dem Konto, die bei anderen API-Aufrufen verwendet wird.

Der Drittanbieter von App-Analysetools führt einen API-Aufruf so aus:

• linked-customer-id: Das App-Analysetool-Konto des Drittanbieters, über das die Daten hochgeladen werden (Konto B).
• customer-id: Das Google Ads-Konto, in das Daten hochgeladen werden (accountA).
• Header login-customer-id und Authorization: Eine Kombination aus 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 Debugging-Zwecken zu protokollieren.

request-id

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