Dieser Leitfaden enthält Beispiele für den direkten Aufruf der REST-Endpunkte ohne die Verwendung einer Clientbibliothek.
Vorbereitung
Alle folgenden Beispiele sollen in ein Bash-Verfahren kopiert und eingefügt werden. curl-Befehl.
Sie benötigen außerdem ein Entwickler-Token, testen Sie Kontozugriff zulässig ist und Google Ads-Verwaltungskonto mit mindestens einem Kundenkonto.
Umgebungsvariablen
Geben Sie unten die Anmeldedaten und IDs für das Konto ein und kopieren Sie sie in Ihr um die in den nachfolgenden Beispielen verwendeten Umgebungsvariablen zu konfigurieren. Im Autorisierungsleitfaden finden Sie eine Anleitung zum Erstellen eines OAuth 2.0-Zugriffstoken.
API_VERSION="17"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"
Zusätzliche optionale Objekt-IDs
Einige der folgenden Beispiele funktionieren mit bereits vorhandenen Budgets oder Kampagnen. Wenn Sie IDs vorhandener Objekte haben, die in diesen Beispielen verwendet werden sollen, geben Sie sie unten ein.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
Andernfalls wird mit den beiden Optionen Mutates – Erstellt Beispiele ein neues Budget erstellt. und Kampagne.
Suchen
Der Leitfaden Query Cookbook enthält viele die den Standardbildschirmen von Google Ads entsprechen und mit die in diesem Leitfaden verwendet werden. Unsere interaktive Abfrage Website-Builder auch eine großartige Ressource zum interaktiven Erstellen benutzerdefinierter Abfragen.
Mit Seitenumbruch
Die Methode search
verwendet Paginierung mit einer festen Seitengröße von 10.000 Elementen und
Eine page_token
, die neben query
angegeben ist.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' ", "page_token":"${PAGE_TOKEN}" }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Streaming
Mit der Methode searchStream
werden alle Ergebnisse in einer einzigen Antwort gestreamt. Somit wird der
Das Feld pageSize
wird nicht unterstützt.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Änderung
Es können mehrere mutate-Vorgänge (create
, update
oder remove
) in einem
einzelnen JSON-Anfragetext durch Ausfüllen des operations
-Arrays.
Erstellt
In diesem Beispiel werden zwei gemeinsame Kampagnenbudgets in einer einzelnen Anfrage erstellt.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } }, { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } } ] }"
Im nächsten Beispiel wird ein BUDGET_ID
eines vorhandenen Kampagnenbudgets verwendet. können Sie
aus der Ausgabe des vorherigen Schritts kopieren und einfügen.
BUDGET_ID=BUDGET_ID
Ressourcen, die auf andere Ressourcen verweisen,
Ressourcenname. Die unten erstellte Kampagne
verweist auf einen campaignBudget
durch seinen Ressourcennamen mit Stringwert.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}', 'targetSpend': {} } } ] }"
Updates
Attribute vorhandener Objekte mithilfe von update
-Vorgängen aktualisieren. Die nächste
Beispiel: Eine bestehende Kampagne wird verwendet. können Sie aus der vorherigen Liste
die Ausgabe des Schritts.
CAMPAIGN_ID=CAMPAIGN_ID
Alle Updates erfordern ein updateMask
-Feld, eine durch Kommas getrennte Liste von
welche JSON-Attribute in der Anfrage enthalten sein sollen,
aktualisieren. Attribute, die in updateMask
aufgeführt, aber nicht in der Anfrage vorhanden sind
Textkörper aus einem Objekt gelöscht werden. Attribute, die nicht in der updateMask
aufgeführt sind, aber vorhanden sind
im Anfragetext, werden ignoriert.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'name': 'A changed campaign name #${RANDOM}', }, 'updateMask': 'name' } ], }"
Entfernen
Um Objekte zu entfernen, geben Sie ihren Ressourcennamen als remove
-Vorgang an.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}' } ], }"
Teilfehler
Wenn mehrere Vorgänge in einer einzigen Anfrage enthalten sind, geben Sie optional an.
partialFailure
Bei true
werden erfolgreiche Vorgänge ausgeführt und
Bei ungültigen Vorgängen werden Fehler zurückgegeben. Bei false
werden alle Vorgänge in der Anfrage
wenn und nur wenn sie gültig sind.
Im nächsten Beispiel wird eine vorhandene Kampagne verwendet. können Sie aus dem Menü Beispielausgabe erstellt:
CAMPAIGN_ID=CAMPAIGN_ID
Die folgende Anfrage enthält zwei Vorgänge. Der erste Versuch,
Gebotsstrategie der angegebenen Kampagne zu erstellen, und in der nächsten wird versucht, eine
Kampagne mit einer ungültigen ID. Da der zweite Vorgang zu einem Fehler führt (der
Kampagnen-ID ungültig) ist und weil partialFailure
auf false
gesetzt ist, wird der
schlägt auch die erste Operation fehl und die Gebotsstrategie der
nicht aktualisiert.
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'partialFailure': false, 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'manualCpc': { 'enhancedCpcEnabled': false } }, 'updateMask': 'manual_cpc.enhanced_cpc_enabled' }, { 'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID' } ] }"
Gruppierte Vorgänge
Die Methode googleAds:mutate
unterstützt das Senden von Gruppen von Vorgängen mit
unterschiedliche Ressourcentypen. Sie können viele Vorgänge unterschiedlicher Typen an
eine Abfolge von Operationen
verketten, die als Gruppe ausgeführt werden sollten.
Die Gruppe von Vorgängen ist erfolgreich, wenn kein Vorgang fehlschlägt oder alle scheitern, falls vorhanden.
einzelner Vorgang schlägt fehl.
In diesem Beispiel wird gezeigt, wie Sie ein Kampagnenbudget, eine Kampagne, eine Anzeigengruppe und Anzeigen zusammen als eine Reihe von Aktionen. Jeder aufeinanderfolgende Vorgang hängt davon ab, auf dem vorherigen. Wenn einer fehlschlägt, schlägt die gesamte Gruppe von Vorgängen fehl.
Negative Ganzzahlen (-1
, -2
, -3
) werden als Platzhalter in der Ressource verwendet.
Namen und werden zur Laufzeit dynamisch mit den Ergebnissen der Sequenz ausgefüllt.
der Betriebsabläufe.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'mutateOperations': [ { 'campaignBudgetOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'name': 'My Campaign Budget #${RANDOM}', 'deliveryMethod': 'STANDARD', 'amountMicros': 500000, 'explicitlyShared': false } } }, { 'campaignOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2', 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'targetSpend': {} } } }, { 'adGroupOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3', 'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2', 'name': 'My ad group #${RANDOM}', 'status': 'PAUSED', 'type': 'SEARCH_STANDARD' } } }, { 'adGroupAdOperation': { 'create': { 'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3', 'status': 'PAUSED', 'ad': { 'responsiveSearchAd': { 'headlines': [ { 'pinned_field': 'HEADLINE_1', 'text': 'An example headline' }, { 'text': 'Another example headline' }, { 'text': 'Yet another headline' } ], 'descriptions': [ { 'text': 'An example description' }, { 'text': 'Another example description' } ], 'path1': 'all-inclusive', 'path2': 'deals' }, 'finalUrls': ['https://www.example.com'] } } } } ] }"
Kontoverwaltung
Erstellen von Konten
Erstellen Sie neue Konten mit der Methode createCustomerClient
. Die URL
erfordert die ID eines Verwaltungskontos anstelle einer Kundenkonto-ID. Ein neuer Kunde
wird im Verwaltungskonto erstellt.
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'customerClient': { 'descriptiveName': 'My Client #${RANDOM}', 'currencyCode': 'USD', 'timeZone': 'America/New_York' } }"
Zugängliche Konten auflisten
Verwenden Sie eine einfache GET
-Anfrage an die Methode listAccessibleCustomers
, um eine Liste abzurufen
von Google Ads-Konten, auf die mit dem angegebenen OAuth 2.0-Zugriffstoken zugegriffen werden kann. Kein Manager
oder Kundenkonto-IDs verwendet werden sollen.
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
Binäre Assets hochladen
Die Methode assets:mutate
wird zum Hochladen und Verwalten verwendet
Assets: Binärdaten, z. B. ein Bild, werden wie folgt codiert:
String mit der standardmäßigen base64-Codierung mit Padding. Entweder Standard- oder
URL-sichere Base64-Codierungen mit oder ohne Padding werden akzeptiert.
In diesem Beispiel wird ein 1-Pixel-GIF codiert, um das Beispiel prägnant zu halten. In der Praxis bedeutet das
data
-Nutzlasten sind viel größer.
Verwenden Sie das Befehlszeilendienstprogramm base64
(Teil von
GNU-Kerndienstprogramme)
um ein 1-Pixel-GIF-Bild zu codieren.
base64 1pixel.gif
Der base64-codierte Wert wird in einer API-Anfrage als data
-Attribut angegeben.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My image asset #${RANDOM}', 'type': 'IMAGE', 'imageAsset': { 'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA' } } } ] }"