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 zur Interaktion mit der API verwenden, müssen Sie sich keine Gedanken über die zugrunde liegenden Anfragedetails machen. Es kann jedoch hilfreich sein, sich ein wenig über sie zu informieren, wenn Sie Tests und Fehlerbehebungen durchführen.

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

  1. [Preferred] Der Text der Anfrage wird als Protokollzwischenspeicher erstellt, mit HTTP/2 an den Server gesendet, die Antwort auf einen Protokollzwischenspeicher defragmentiert und die Ergebnisse ausgewertet. In der Großteil unserer Dokumentation wird die Verwendung von gRPC beschrieben.

  2. [Optional] Erstellen Sie den Anfragetext als JSON-Objekt, senden Sie ihn mithilfe von 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 zu REST.

Ressourcennamen

Die meisten Objekte in der API werden über die Ressourcennamenstrings identifiziert. Diese Strings dienen auch als URLs, wenn die REST-Schnittstelle verwendet wird. Informationen zur Struktur der REST-Schnittstelle und den Ressourcennamen

Zusammengesetzte IDs

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

Weil die Anzeigen-ID einer Anzeigengruppe beispielsweise nicht global eindeutig ist, stellen wir der ID des übergeordneten Objekts (der Anzeigengruppe) die entsprechende ID 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, die den Text der Anfrage ergänzen (oder gRPC-Metadaten):

Autorisierung

Sie müssen ein OAuth2-Zugriffstoken in Form von Authorization: Bearer YOUR_ACCESS_TOKEN einschließen, das entweder ein Verwaltungskonto, das im Namen eines Kunden fungiert, oder einen Werbetreibenden verwaltet, der sein Konto selbst verwaltet. Eine Anleitung zum Abrufen eines Zugriffstokens finden Sie im OAuth2-Leitfaden. Ein Zugriffstoken ist eine Stunde lang gültig. Nach Ablauf des Zugriffstokens müssen Sie es aktualisieren, um ein neues abzurufen. Abgelaufene Tokens werden von unseren Clientbibliotheken automatisch aktualisiert.

Entwickler-Token

Ein Entwicklertoken ist ein 22-stelliger String, der einen Google Ads API-Entwickler eindeutig identifiziert. Ein Beispiel für einen Entwickler-Token-String ist ABcdeFGH93KL-NOPQ_STUv. Das Entwicklertoken sollte im Format developer-token : ABcdeFGH93KL-NOPQ_STUv enthalten sein.

Login-Kunden-ID

Die Kundennummer des autorisierten Kunden für die Anfrage ohne Bindestriche (-). Wenn der Zugriff auf das Kundenkonto über ein Verwaltungskonto erfolgt, ist dieser Header erforderlich und muss auf die Kundennummer des Verwaltungskontos gesetzt werden.

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

Wenn Sie login-customer-id festlegen, entspricht dies der Auswahl eines Kontos in der Google Ads-UI, nachdem Sie sich rechts oben auf Ihr Profilbild angemeldet oder darauf geklickt haben. Wenn Sie diesen Header nicht angeben, wird standardmäßig der operative Kunde verwendet.

Link-Kunden-ID

Dieser Header wird nur von App-Drittanbietern beim Hochladen von Conversions in ein verknüpftes Google Ads-Konto verwendet.

Angenommen, Nutzer im Konto A gewähren über einen ThirdPartyAppAnalyticsLink Lese- und Bearbeitungszugriff auf ihre Entitäten, um B auf das Konto anzuwenden. Nach der Verknüpfung kann ein Nutzer im Konto B API-Aufrufe für das Konto A ausführen. Dabei gelten die Berechtigungen, die über den Link angegeben werden. In diesem Fall werden die API-Aufrufberechtigungen für das Konto A durch die Drittanbieterverknüpfung zum Konto B bestimmt und nicht durch die Verwaltungskontobeziehung, die in anderen API-Aufrufen verwendet wird.

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

  • linked-customer-id: Das App-Analysetool eines Drittanbieters, das die Daten hochlädt (Konto B).
  • customer-id: Das Google Ads-Konto, in das die Daten hochgeladen werden (Konto A).
  • Header login-customer-id und Authorization: Eine Kombination von Werten, die einen Nutzer identifizieren, der Zugriff auf das Konto B hat.

Antwortheader

Die folgenden Header (oder gRPC nachgestellter-Metadaten) werden mit dem Antworttext zurückgegeben. Wir empfehlen, diese Werte zur Fehlerbehebung zu protokollieren.

Anfrage-ID

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