Diese Anleitung enthält Beispiele für den direkten Aufruf der REST-Endpunkte ohne Verwendung einer Clientbibliothek.
Weitere Codebeispiele finden Sie im REST-Codebeispiele GitHub-Repository.
Die Anfragen- und Antworttexte für die einzelnen API-Methoden finden Sie in der Referenzdokumentation für die jeweiligen Dienstendpunkte.
Auf der Referenzseite
für GoogleAdsService.Search sind beispielsweise die Anfragen- und Antworttexte für die
Search Methode zu sehen.
Vorbereitung
Alle hier gezeigten Beispiele sind so konzipiert, dass sie mit dem Befehl curl in eine bash shell kopiert und eingefügt werden können.
Sie benötigen außerdem ein Entwicklertoken. Der Zugriff auf ein Test konto ist ausreichend. Außerdem benötigen Sie ein Google Ads-Verwaltungskonto mit mindestens einem Kundenkonto.
Umgebungsvariablen
Geben Sie die Kontodaten und IDs wie gezeigt ein und kopieren Sie sie dann in Ihr Terminal, um die Umgebungsvariablen zu konfigurieren, die in den folgenden Beispielen verwendet werden. In der Anleitung zur Autorisierung finden Sie eine Anleitung zum Generieren eines OAuth 2.0-Zugriffstokens.
API_VERSION="25"
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 beziehen sich auf bereits vorhandene Budgets oder Kampagnen. Wenn Sie IDs vorhandener Objekte haben, die Sie mit diesen Beispielen verwenden möchten, geben Sie sie wie gezeigt ein.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_IDAndernfalls werden in den beiden Beispielen für Mutates – Creates ein neues Budget und eine neue Kampagne erstellt.
Suchen
Die Anleitung Query Cookbook enthält viele Berichts beispiele, die einigen der Standardbildschirme von Google Ads entsprechen und mit denselben Umgebungsvariablen wie in dieser Anleitung funktionieren. Unser interaktives Tool zur Abfrageerstellung ist ebenfalls eine gute Ressource, um benutzerdefinierte Abfragen interaktiv zu erstellen.
Mit Seitenumbruch
Die Methode search verwendet die Paginierung mit einer festen Seitengröße von 10.000 Elementen und einem page_token, das neben der query angegeben wird.
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
Die Methode searchStream streamt alle Ergebnisse in einer einzigen Antwort. Daher wird das Feld pageSize 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'
Mutates
Mehrere Mutate-Vorgänge (create, update oder remove) können in einem einzigen JSON-Anfragetext gesendet werden, indem Sie das Array operations ausfüllen.
Creates
In diesem Beispiel werden zwei gemeinsame Kampagnenbudgets in einer einzigen 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 eine BUDGET_ID eines vorhandenen Kampagnenbudgets verwendet. Sie können sie aus der Ausgabe des vorherigen Schritts kopieren und einfügen.
BUDGET_ID=BUDGET_IDRessourcen, die auf andere Ressourcen verweisen, tun dies über den
Ressourcennamen. Die im folgenden Beispiel erstellte Kampagne verweist über ihren String-Ressourcennamen auf ein campaignBudget.
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
Aktualisieren Sie Attribute vorhandener Objekte mit update-Vorgängen. Im nächsten Beispiel wird eine vorhandene Kampagne verwendet. Sie können sie aus der Ausgabe des vorherigen Schritts kopieren und einfügen.
CAMPAIGN_ID=CAMPAIGN_IDFür alle Aktualisierungen ist ein Feld updateMask erforderlich. Dabei handelt es sich um eine durch Kommas getrennte Liste der JSON-Attribute, die in der Anfrage enthalten sein und als Aktualisierung angewendet werden sollen. Attribute, die in updateMask aufgeführt sind, aber nicht im Anfragetext enthalten sind, werden für ein Objekt gelöscht. Attribute, die nicht in updateMask aufgeführt sind, aber im Anfragetext enthalten sind, 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
Objekte werden entfernt, indem ihr Ressourcenname als remove-Vorgang angegeben wird.
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}' } ], }"
Teilweise fehlgeschlagene Vorgänge
Wenn mehrere Vorgänge in einer einzigen Anfrage enthalten sind, können Sie optional partialFailure angeben. Wenn true festgelegt ist, werden erfolgreiche Vorgänge ausgeführt und bei ungültigen Vorgängen werden Fehler zurückgegeben. Wenn false festgelegt ist, sind alle Vorgänge in der Anfrage nur dann erfolgreich, wenn sie alle gültig sind.
Im nächsten Beispiel wird eine vorhandene Kampagne verwendet. Sie können sie aus der Creates Ausgabe des Beispiels kopieren und einfügen.
CAMPAIGN_ID=CAMPAIGN_IDDie folgende Anfrage enthält zwei Vorgänge. Beim ersten Vorgang wird versucht, die Gebotsstrategie der angegebenen Kampagne zu ändern. Beim zweiten Vorgang wird versucht, eine Kampagne mit einer ungültigen ID zu entfernen. Da der zweite Vorgang zu einem Fehler führt (die Kampagnen-ID ist ungültig) und partialFailure auf false festgelegt ist, schlägt auch der erste Vorgang fehl und die Gebotsstrategie der vorhandenen Kampagne wird 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 Vorgangsgruppen mit mehreren Ressourcentypen. Sie können viele Vorgänge verschiedener Typen senden, um eine Abfolge von Vorgängen zu verketten, die als Gruppe ausgeführt werden sollen.
Die Vorgangsgruppe ist erfolgreich, wenn kein Vorgang fehlschlägt. Wenn ein einzelner Vorgang fehlschlägt, schlagen alle Vorgänge fehl.
In diesem Beispiel wird gezeigt, wie Sie ein Kampagnenbudget, eine Kampagne, eine Anzeigengruppe und eine Anzeige als einzelne Gruppe von Aktionen erstellen. Jeder nachfolgende Vorgang hängt vom vorherigen ab. Wenn ein Vorgang fehlschlägt, schlägt die gesamte Vorgangsgruppe fehl.
Negative Ganzzahlen (-1, -2, -3) werden in den Ressourcennamen als Platzhalter verwendet und zur Laufzeit dynamisch mit den Ergebnissen der Vorgangsabfolge gefüllt.
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
Sie können Konten erstellen, zugängliche Konten auflisten und binäre Assets hochladen.
Konten erstellen
Erstellen Sie neue Konten mit der Methode createCustomerClient. Beachten Sie, dass für die URL eine Verwaltungskonto-ID anstelle einer Kundenkonto-ID erforderlich ist. Unter dem Verwaltungskonto wird ein neues Kundenkonto 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 der Google Ads-Konten abzurufen, auf die mit dem angegebenen OAuth 2.0-Zugriffstoken zugegriffen werden kann. In dieser Anfrage dürfen keine Verwaltungskonto- oder Kundenkonto-IDs verwendet werden.
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 von
Assets verwendet. Binäre Daten wie ein Bild werden mit der standardmäßigen Base64-Codierung mit Padding als String codiert. Es werden sowohl die standardmäßige als auch die URL-sichere Base64-Codierung mit oder ohne Padding akzeptiert.
In diesem Beispiel wird ein 1-Pixel-GIF codiert, um das Beispiel kurz zu halten. In der Praxis sind die data-Nutzlasten viel größer.
Verwenden Sie das base64 Befehlszeilentool (Teil der
GNU-Core-Dienstprogramme)
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' } } } ] }"