API-Aufrufstruktur

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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. Beim Testen und Debuggen kann es jedoch hilfreich sein, sich ein bisschen mit ihnen vertraut zu machen.

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

  1. [Bevorzugt] Sie erstellen den Text der Anfrage als Protokollzwischenspeicher, senden ihn mithilfe von HTTP/2 an den Server, deserialisieren die Antwort auf einen Protokollpuffer und interpretieren die Ergebnisse. In den meisten Dokumenten wird die Verwendung von gRPC beschrieben.

  2. [Optional] Erstellen Sie den Anfragetext als JSON-Objekt. Senden Sie ihn dann 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.

Ressourcennamen

Die meisten Objekte in der API werden anhand ihrer 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.

Zusammengesetzte IDs

Wenn die ID eines Objekts nicht global eindeutig ist, wird eine zusammengesetzte ID für das Objekt erstellt. Dazu wird die übergeordnete ID und eine Tilde (~) vorangestellt.

Da die Anzeigen-ID einer Anzeigengruppe beispielsweise nicht eindeutig ist, stellen wir ihr die übergeordnete Objekt-ID (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 den Text der Anfrage begleitet:

Autorisierung

Sie müssen ein OAuth2-Zugriffstoken im Format Authorization: Bearer YOUR_ACCESS_TOKEN angeben, das entweder ein Verwaltungskonto, das im Namen eines Kunden handelt, oder einen Werbetreibenden identifiziert, 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. Wenn es abläuft, aktualisieren Sie das Zugriffstoken, um ein neues abzurufen. Abgelaufene Tokens werden von unseren Clientbibliotheken automatisch aktualisiert.

Entwicklertoken

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

Log-in-Kundennummer

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

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

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

verknüpfte Kundennummer

Dieser Header wird nur vom App-Analysetool eines Drittanbieters verwendet, wenn Conversions in ein verknüpftes Google Ads-Konto hochgeladen werden.

Stellen Sie sich das Szenario vor, in dem Nutzer des Kontos A über eine 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 API-Aufrufe an das Konto A senden, vorbehaltlich der Berechtigungen, die durch die Verknüpfung gewährt werden. In diesem Fall werden die API-Aufrufberechtigungen für das Konto A über die Drittanbieterverknüpfung zum Konto B ermittelt und nicht über die Verwaltungskontobeziehung, die in anderen API-Aufrufen verwendet wird.

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

  • linked-customer-id: Das Konto eines Drittanbieters für App-Analysen, 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 zur Identifizierung eines Nutzers mit Zugriff auf das Konto B.

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.