Beispiele

Dieser Leitfaden enthält Beispiele für den direkten Aufruf der REST-Endpunkte ohne Verwendung einer Clientbibliothek.

Vorbereitung

Alle folgenden Beispiele sind mit dem Befehl curl in eine Bash-Shell zu kopieren und einzufügen.

Außerdem benötigen Sie ein Entwickler-Token (Zugriff auf ein Testkonto ist ausreichend) und ein Google Ads-Verwaltungskonto mit mindestens einem Kundenkonto.

Wichtig :In diesen Beispielen gehen wir davon aus, dass Sie über einen Nutzer mit Administratorzugriff auf ein Verwaltungskonto (MANAGER_CUSTOMER_ID) auf ein Kundenkonto (CUSTOMER_ID) zugreifen, das direkt das Kundenkonto verwaltet. Wenn Sie stattdessen direkt auf ein einzelnes Kundenkonto zugreifen, lassen Sie den login-customer-id-Header weg oder setzen Sie ihn auf denselben Wert wie CUSTOMER_ID. Für einige Beispiele, z. B. Konten erstellen, ist ein Verwaltungskonto erforderlich.

Umgebungsvariablen

Geben Sie unten die Anmeldedaten und IDs für das Konto ein und kopieren Sie sie dann in Ihr Terminal, um die Umgebungsvariablen zu konfigurieren, die in den folgenden Beispielen verwendet werden. Im Leitfaden zur Autorisierung finden Sie eine Anleitung zum Generieren eines OAuth 2.0-Zugriffstokens.

API_VERSION="19"
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 für bereits vorhandene Budgets oder Kampagnen. Wenn Sie IDs vorhandener Objekte haben, die Sie mit diesen Beispielen verwenden möchten, geben Sie sie unten ein.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Andernfalls werden mit den beiden Mutates – Creates examples (Änderungen – Beispiele erstellen) ein neues Budget und eine neue Kampagne erstellt.

Suchen

Der Leitfaden Query Cookbook enthält viele Berichtsbeispiele, die einigen der Standardbildschirme in Google Ads entsprechen und mit denselben Umgebungsvariablen wie in diesem Leitfaden funktionieren. Unser Tool für interaktive Abfragen eignet sich auch hervorragend, um benutzerdefinierte Abfragen interaktiv zu erstellen.

Mit Seitenumbruch

Bei der search-Methode wird die Paginierung mit einer festen Seitengröße von 10.000 Elementen verwendet. Außerdem wird neben query ein page_token angegeben.

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

Bei der searchStream-Methode werden alle Ergebnisse in einer einzigen Antwort gestreamt. Das Feld pageSize wird daher 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'

Mutiert

Mehrere Mutate-Vorgänge (create, update oder remove) können in einem einzigen JSON-Anfragetextkörper gesendet werden, indem das operations-Array ausgefüllt wird.

Erstellt

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 ein BUDGET_ID eines vorhandenen Kampagnenbudgets verwendet. Sie können die Ausgabe des vorherigen Schritts kopieren und einfügen.

BUDGET_ID=BUDGET_ID

Ressourcen, die auf andere Ressourcen verweisen, tun dies über den Ressourcennamen. Die unten erstellte Kampagne verweist über den Ressourcennamen mit 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

Aktualisieren Sie Attribute vorhandener Objekte mithilfe von update-Vorgängen. 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

Für alle Aktualisierungen ist ein updateMask-Feld erforderlich. Das ist 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, aber nicht im Anfragetext enthalten sind, werden für ein Objekt gelöscht. Attribute, die in updateMask nicht aufgeführt, 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

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 einzelnen Anfrage enthalten sind, geben Sie optional partialFailure an. 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 alle gültig sind.

Im nächsten Beispiel wird eine vorhandene Kampagne verwendet. Sie können die Ausgabe aus dem Beispiel Erstellt kopieren und einfügen.

CAMPAIGN_ID=CAMPAIGN_ID

Die folgende Anfrage enthält zwei Vorgänge. Beim ersten wird versucht, die Gebotsstrategie der angegebenen Kampagne zu ändern. Beim 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 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 Gruppen von Vorgängen 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 Vorgänge sind erfolgreich, wenn keiner fehlschlägt. Andernfalls schlagen alle fehl.

In diesem Beispiel wird gezeigt, wie Sie ein Kampagnenbudget, eine Kampagne, eine Anzeigengruppe und eine Anzeige mit nur einer Aktion erstellen. Jeder nachfolgende Vorgang hängt vom vorherigen 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 werden zur Laufzeit dynamisch mit den Ergebnissen der Abfolge von Vorgängen ausgefü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

Neue Konten mit der Methode createCustomerClient erstellen. Für die URL ist die ID eines Verwaltungskontos anstelle der ID eines Kundenkontos erforderlich. Im 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'
}
}"

Konten mit Zugriffsberechtigung auflisten

Mit einer einfachen GET-Anfrage an die listAccessibleCustomers-Methode können Sie eine Liste der Google Ads-Konten abrufen, auf die mit dem angegebenen OAuth 2.0-Zugriffstoken zugegriffen werden kann. In dieser Anfrage dürfen keine Verwaltungs- 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 assets:mutate-Methode wird zum Hochladen und Verwalten von Assets verwendet. Binärdaten wie Bilder werden mit der standardmäßigen Base64-Codierung mit Padding als String codiert. Es wird entweder die Standard- oder die URL-sichere Base64-Codierung mit oder ohne Padding akzeptiert.

In diesem Beispiel wird ein GIF mit nur einem Pixel codiert, um das Beispiel prägnant zu halten. In der Praxis sind die data-Nutzlasten viel größer.

Verwenden Sie das Befehlszeilentool base64 (Teil der GNU core utilities), um ein GIF-Bild mit 1 Pixel 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'
      }
    }
  }
]
}"