API-Aufrufstruktur

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

Wenn Sie eine Clientbibliothek verwenden, um mit der API zu interagieren, müssen Sie sich keine Gedanken über die zugrunde liegenden Anfragedetails machen. Wenn Sie jedoch ein wenig darüber wissen, kann das beim Testen und Beheben von Fehlern hilfreich sein.

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

1. [Bevorzugt] Erstellen Sie den Textkörper der Anfrage als Protokoll-Buffer, senden Sie ihn mit HTTP/2 an den Server, deserialisieren Sie die Antwort in einen Protokoll-Buffer und interpretieren Sie die Ergebnisse. In der meisten unserer Dokumentation wird die Verwendung von gRPC beschrieben.

2. [Optional] Erstellen Sie den Anfragetext als JSON-Objekt, senden Sie ihn mit 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-Oberfläche.

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

Ressourcennamen

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

Wichtiger Hinweis: In der Dokumentation zu Ressourcen finden Sie alle unterstützten Ressourcen und ihre Pfaddarstellung (resource_name). Das gleiche Format wird 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 ein Tilde (~) vorangestellt werden.

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

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

Anfrageheader

Das sind die HTTP-Header (oder GRPC-Metadaten), die dem Textkörper 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 handelt, oder einen Werbetreibenden, der sein eigenes Konto direkt verwaltet. Eine Anleitung zum Abrufen eines Zugriffstokens findest du im OAuth2-Leitfaden. Ein Zugriffstoken ist nach dem Abrufen eine Stunde lang gültig. Wenn es abläuft, aktualisiere das Zugriffstoken, um ein neues abzurufen. Abgelaufene Tokens werden von unseren Clientbibliotheken automatisch aktualisiert.

developer-token

Ein Entwicklertoken ist eine Zeichenfolge mit 22 Zeichen, mit der ein Google Ads API-Entwickler eindeutig identifiziert wird. Ein Beispiel für einen Entwicklertoken-String ist ABcdeFGH93KL-NOPQ_STUv. Das Entwicklertoken muss das Format developer-token : ABcdeFGH93KL-NOPQ_STUv haben.

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

Schlüsselbegriff: Der Nutzer ist die Kunden-ID in der Anfragen-Nutzlast. In der folgenden CampaignBudgetService-Anfrage ist 1234567890 beispielsweise der Kunde, der die Nutzung verwaltet:

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

Das Festlegen des login-customer-id entspricht dem Auswählen 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 angeben, wird standardmäßig der Nutzer verwendet.

Hinweis: Sie können eine Liste der Konten abrufen, auf die direkt mit Ihren OAuth-Anmeldedaten zugegriffen werden kann. Dazu müssen Sie eine CustomerService.ListAccessibleCustomers-Anfrage senden. 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 für App-Analysen verwendet, wenn Conversions in ein verknüpftes Google Ads-Konto hochgeladen werden.

Angenommen, Nutzer des Kontos A gewähren dem Konto B über eine ThirdPartyAppAnalyticsLink Lese- und Bearbeitungszugriff auf seine Entitäten. Nach der Verknüpfung kann ein Nutzer des Kontos B API-Aufrufe an das Konto A senden, sofern die entsprechenden Berechtigungen durch die Verknüpfung gewährt wurden. In diesem Fall werden die Berechtigungen für API-Aufrufe für das Konto A durch die Drittanbieterverknüpfung mit dem Konto B bestimmt, nicht durch die Beziehung zum Verwaltungskonto, die bei anderen API-Aufrufen verwendet wird.

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

• linked-customer-id: Das Konto für App-Analysen von Drittanbietern, über das die Daten hochgeladen werden (Konto B).
• customer-id: Das Google Ads-Konto, in das Daten hochgeladen werden (KontoA).
• login-customer-id- und Authorization-Header: Eine Kombination von Werten, um einen Nutzer zu identifizieren, 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 protokollieren, um Fehler zu beheben.

request-id

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