API-Aufrufstruktur

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

Wenn Sie eine Clientbibliothek für die Interaktion mit der API verwenden, um die zugrunde liegenden Anfragedetails zu kümmern. Sie können jedoch ein wenig über sie zu wissen, kann beim Testen und bei der Fehlerbehebung hilfreich sein.

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

1. [Preferred] Erstellen Sie den Anfragetext als Protokollzwischenspeicher, senden Sie ihn mithilfe von HTTP/2, deserialisieren Sie die Antwort auf ein Protokoll. und die Ergebnisse zu interpretieren. In unserer Dokumentation wird meist die Verwendung gRPC.

2. [Optional] Erstellen Sie den Anfragetext als JSON-Objekt zu erstellen, senden Sie es über HTTP 1.1 an den Server, die Antwort als JSON-Objekt deserialisieren und die Ergebnisse interpretieren. Weitere Informationen finden Sie unter im Leitfaden zur REST-Oberfläche finden Sie weitere Informationen zur Verwendung von REST.

Hinweis: In diesem Leitfaden werden die Struktur- und Transport-Header beschrieben, die beiden gRPC- und REST-Protokolle.

Ressourcennamen

Die meisten Objekte in der API werden anhand ihrer Ressourcennamenstrings identifiziert. Diese dienen auch als URLs, wenn Sie die REST-Schnittstelle verwenden. REST ansehen Ressourcennamen für ihre Struktur.

Wichtiger Hinweis: Sehen Sie sich die Ressourcendokumentation an. für 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, eine zusammengesetzte ID für dieses Objekt wird durch Voranstellen der übergeordneten ID und einer Tilde (~) erstellt.

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

• AdGroupId von 123 + ~ + AdGroupAdId von 45678 = zusammengesetzte Anzeige Gruppenanzeigen-ID von 123~45678.

Anfrageheader

Dies sind die HTTP-Header (oder grpc-Header Metadaten). den Text in der Anfrage:

Autorisierung

Sie müssen ein OAuth2-Zugriffstoken in Form von Authorization: Bearer YOUR_ACCESS_TOKEN, die entweder ein Verwaltungskonto, das direkt im Namen eines Kunden oder Werbetreibenden handelt sein Konto selbst verwalten. Anleitung zum Abrufen eines Zugriffstokens finden Sie im OAuth2-Leitfaden. Eine Das Zugriffstoken ist nach Erhalt eine Stunde lang gültig. wenn es abgelaufen ist, aktualisieren Sie das Zugriffstoken, um ein neues abzurufen. Beachten Sie, dass aktualisieren unsere Client-Bibliotheken abgelaufene Tokens automatisch.

developer-token

Ein Entwickler-Token ist eine 22 Zeichen lange Zeichenfolge, die ein Google Ads API-Entwickler. Ein Beispiel für einen Entwickler-Token-String ist ABcdeFGH93KL-NOPQ_STUv Das Entwickler-Token sollte im Form von developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Dies ist die Kundennummer des autorisierten Kunden, der in der Anfrage verwendet werden soll. ohne Bindestriche (-). Wenn Sie über eine Verwaltungskonto enthält, ist dieser Header erforderlich und muss auf die Kundennummer festgelegt werden von mit dem Verwaltungskonto.

Wichtiger Begriff: Der Betreibende Kunde ist die Kundennummer in der Anfragenutzlast. Beispiel: Der Betriebskunde CampaignBudgetService-Anfrage ist 1234567890:

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

Das Festlegen von login-customer-id entspricht der Auswahl eines Kontos in der Google Ads-Benutzeroberfläche, nachdem Sie sich angemeldet oder oben auf Ihr Profilbild geklickt haben genau. Ohne diesen Header wird standardmäßig das Feld operator Kunde.

Hinweis :Sie können die Liste der Konten abrufen, auf die direkt über die OAuth-Anmeldedaten CustomerService.ListAccessibleCustomers login-customer-id ist für diesen Anfragetyp nicht erforderlich. hat keine Auswirkungen auf die Liste der zurückgegebenen Kunden.

linked-customer-id

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

Stellen Sie sich ein Szenario vor, bei dem Nutzer im Konto A Lese- und Bearbeitungszugriff gewähren Konto B über eine ThirdPartyAppAnalyticsLink Nach der Verknüpfung kann ein Nutzer des Kontos B API-Aufrufe an das Konto A senden. unterliegen den Berechtigungen, die über den Link gewährt werden. In diesem Fall werden die API-Aufrufe Berechtigungen für das Konto A werden durch den Drittanbieterlink zum Konto B bestimmt, und nicht in der Verwaltungskonto-Konto-Beziehung, die in anderen API-Aufrufen verwendet wird.

Der Drittanbieter des App-Analysetools führt einen API-Aufruf wie folgt aus:

• linked-customer-id: Das Drittanbieterkonto für App-Analysen, das hochgeladen wird die Daten (Konto B).
• customer-id: das Google Ads-Konto, in das die Daten hochgeladen werden (Konto) A).
• login-customer-id- und Authorization-Header: Eine Kombination aus Werten, die einen Nutzer identifizieren, der Zugriff auf das Konto B hat

Antwortheader

Die folgenden Überschriften (oder grpc fronting-metadata) mit dem Antworttext zurückgegeben. Wir empfehlen, diese zu Debugging-Zwecken.

Anfrage-ID

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