Dieser Leitfaden enthält Beispiele für den direkten Aufruf der REST-Endpunkte ohne Verwendung einer Clientbibliothek.
Voraussetzungen
Alle folgenden Beispiele sollen mit dem Befehl curl kopiert und in eine Bash-Shell eingefügt werden.
Außerdem benötigen Sie ein Entwickler-Token, Zugriff auf das Testkonto und ein Google Ads-Verwaltungskonto mit mindestens einem Kundenkonto.
Umgebungsvariablen
Geben Sie unten die Anmeldedaten und IDs des Kontos ein und kopieren Sie diese dann in Ihr Terminal, um die in den nachfolgenden Beispielen verwendeten Umgebungsvariablen zu konfigurieren. Im Autorisierungsleitfaden finden Sie eine Anleitung zum Generieren eines OAuth 2.0-Zugriffstokens.
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 für diese Beispiele haben, geben Sie sie unten ein.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
Andernfalls werden mit den beiden Optionen Mutates – Erstellt Beispiele ein neues Budget und eine neue Kampagne erstellt.
Suche
Der Leitfaden für Abfragen enthält viele Berichtsbeispiele, die einigen Google Ads-Standardbildschirmen entsprechen und mit den in diesem Leitfaden verwendeten Umgebungsvariablen arbeiten. Mit unserem interaktiven Query Builder können Sie ebenfalls sehr gut benutzerdefinierte Abfragen erstellen.
Mit Seitenumbruch
Die Methode search
verwendet Paginierung mit einer festen Seitengröße von 10.000 Elementen und einem page_token
, das neben 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
Mit der Methode searchStream
werden alle Ergebnisse in einer einzigen Antwort gestreamt. 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'
Änderung
Sie können mehrere mutate-Vorgänge (create
, update
oder remove
) in einem einzelnen JSON-Anfragetext senden. Füllen Sie dazu das Array operations
aus.
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. Sie können die Ausgabe des vorherigen Schritts kopieren und einfügen.
BUDGET_ID=BUDGET_ID
Bei Ressourcen, die auf andere Ressourcen verweisen, wird der Ressourcenname verwendet. Die unten erstellte Kampagne verweist über ihren Ressourcennamen mit einem Stringwert auf eine 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
Attribute vorhandener Objekte mithilfe von update
-Vorgängen aktualisieren. Im nächsten Beispiel wird eine vorhandene Kampagne verwendet. Sie können die Ausgabe des vorherigen Schritts kopieren und einfügen.
CAMPAIGN_ID=CAMPAIGN_ID
Alle Updates erfordern ein updateMask
-Feld, das als Aktualisierung angewendet werden soll. Dabei handelt es sich um eine durch Kommas getrennte Liste der JSON-Attribute, die in der Anfrage enthalten sein sollen. Attribute, die in updateMask
aufgeführt, aber nicht im Anfragetext vorhanden sind, werden für ein Objekt gelöscht. Attribute, die nicht in updateMask
aufgeführt sind, aber im Anfragetext vorhanden 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
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 einzelnen Anfrage enthalten sind, können Sie partialFailure
angeben. Bei true
werden erfolgreiche Vorgänge ausgeführt und ungültige Vorgänge geben Fehler zurück. Bei false
sind alle Vorgänge in der Anfrage nur dann erfolgreich, wenn sie gültig sind.
Im nächsten Beispiel wird eine vorhandene Kampagne verwendet. Sie können sie aus der Ausgabe des Beispiels Creates kopieren und einfügen.
CAMPAIGN_ID=CAMPAIGN_ID
Die folgende Anfrage enthält zwei Vorgänge. Im ersten Schritt wird versucht, die Gebotsstrategie der angegebenen Kampagne zu ändern, und im nächsten 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
gesetzt 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 Gruppen von Vorgängen mit mehreren Arten von Ressourcen. Sie können viele verschiedene Vorgänge senden, um eine Abfolge von Vorgängen zu verketten, die als Gruppe ausgeführt werden sollten.
Die Gruppe von Vorgängen ist erfolgreich, wenn kein Vorgang fehlschlägt oder alle fehlschlagen, wenn ein einzelner Vorgang fehlschlägt.
In diesem Beispiel wird gezeigt, wie Sie ein Kampagnenbudget, eine Kampagne, eine Anzeigengruppe und eine Anzeige als eine Gruppe von Aktionen erstellen. Jeder nachfolgende Vorgang hängt vom vorherigen Vorgang ab. Wenn einer fehlschlägt, schlägt die gesamte Gruppe von Vorgängen fehl.
Negative Ganzzahlen (-1
, -2
, -3
) werden als Platzhalter in den Ressourcennamen verwendet und zur Laufzeit dynamisch mit den Ergebnissen der Sequenz von Vorgängen 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
Erstellen von Konten
Erstellen Sie neue Konten mit der Methode createCustomerClient
. Beachten Sie, dass für die URL die ID eines Verwaltungskontos und keine 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 listAccessibleCustomers
-Methode, 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, z. B. ein Bild, werden mit der standardmäßigen base64-Codierung mit Padding als String codiert. Es ist entweder die Standard- oder die URL-sichere Base64-Codierung mit oder ohne Abstand zulässig.
In diesem Beispiel wird ein 1-Pixel-GIF codiert, um das Beispiel prägnant zu halten. In der Praxis sind die data
-Nutzlasten viel größer.
Verwenden Sie das Befehlszeilendienstprogramm base64
(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' } } } ] }"