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 um die zugrunde liegenden Anfragedetails machen. Es kann jedoch hilfreich sein, sich mit dem Thema vertraut zu machen, wenn Sie Tests und Debugging ausführen möchten.

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

1. [Bevorzugt] Der Text der Anfrage wird als Protokollzwischenspeicher erstellt, mithilfe von HTTP/2 an den Server gesendet, die Antwort auf einen Protokollpuffer deserialisiert und die Ergebnisse interpretiert. Der Großteil der Dokumentation beschreibt die Verwendung von gRPC.

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

Ressourcennamen

Die meisten Objekte in der API werden durch ihre Ressourcennamen-Strings identifiziert. Diese Strings dienen auch als URLs, wenn die REST-Oberfläche verwendet wird. Informationen zur Struktur der REST-Schnittstelle finden Sie unter Ressourcennamen.

Wichtiger Hinweis: In der Ressourcendokumentation finden Sie alle unterstützten Ressourcen und deren Pfaddarstellung (resource_name). Für andere Dienste wird dasselbe Format 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 Anzeigen-ID einer Anzeigengruppe beispielsweise nicht global eindeutig ist, stellen wir ihr die ID des übergeordneten Objekts (Anzeigengruppe) voran, um eine eindeutige zusammengesetzte ID zu erstellen:

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

Anfrageheader

Dies sind die HTTP-Header (oder grpc-Metadaten), die dem Text in der Anfrage hinzugefügt werden:

Autorisierung

Sie müssen ein OAuth2-Zugriffstoken in der Form Authorization: Bearer YOUR_ACCESS_TOKEN angeben, das entweder ein Verwaltungskonto, das im Namen eines Kunden handelt, oder einen Werbetreibenden, der sein eigenes Konto direkt verwaltet, identifiziert. Eine Anleitung zum Abrufen von Zugriffstokens erhalten 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.

Entwickler-Token

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

Login-Kundennummer

Dies ist die Kundennummer des autorisierten Kunden für die Anfrage ohne Bindestriche (-). Wenn Sie über ein Verwaltungskonto auf den Kundenkonto zugreifen, ist dieser Header erforderlich und muss auf die Kundennummer des Verwaltungskontos festgelegt werden.

Wichtiger Begriff:Der funktionierende Kunde ist die Kundennummer in der Nutzlast der Anfrage. Der operative Kunde in der folgenden CampaignBudgetService-Anfrage ist beispielsweise 1234567890:

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

Das Festlegen von login-customer-id entspricht dem Auswählen eines Kontos in der Google Ads-Benutzeroberfläche nach der Anmeldung oder dem Klick auf Ihr Profilbild rechts oben. Wenn Sie diesen Header nicht angeben, wird standardmäßig der Betriebskunde verwendet.

Hinweis: Sie können die Liste der Konten, auf die direkt mit Ihren OAuth-Anmeldedaten zugegriffen werden kann, mit einer CustomerService.ListAccessibleCustomers-Anfrage abrufen. 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 nur von Drittanbietern von App-Analysetools verwendet, wenn Conversions in ein verknüpftes Google Ads-Konto hochgeladen werden.

Stellen Sie sich das Szenario vor, in dem Nutzer im Konto A über einen ThirdPartyAppAnalyticsLink Lese- und Bearbeitungszugriff auf die Entitäten für das Konto B gewähren. Nach der Verknüpfung kann ein Nutzer im Konto B die API-Aufrufe an das Konto A durchführen, sofern die durch den Link bereitgestellten Berechtigungen gewährt werden. In diesem Fall werden die API-Aufrufberechtigungen für das Konto A durch die Drittanbieterverknüpfung mit dem Konto B bestimmt und nicht durch die Verwaltungskontobeziehung, die in anderen API-Aufrufen verwendet wird.

Der App-Analysetools eines Drittanbieters führt einen API-Aufruf aus:

• linked-customer-id: Das App-Analysekonto des Drittanbieters, mit dem 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, 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 Fehlerbehebungszwecken zu protokollieren.

Anfrage-ID

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