Beispiele

Dieser Leitfaden enthält Beispiele für das direkte Aufrufen 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.

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

Umgebungsvariablen

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

API_VERSION="16"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

Weitere optionale Objekt-IDs

Einige der folgenden Beispiele beziehen sich auf bereits vorhandene 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 mithilfe der beiden Mutates – Creates examples (Mutate – Erstellt Beispiele) ein neues Budget und eine neue Kampagne erstellt.

Suche

Der Leitfaden Query Cookbook enthält viele Beispiele für die Berichterstellung, die einigen der Google Ads-Standardbildschirme entsprechen und mit denselben Umgebungsvariablen funktionieren, die in diesem Leitfaden verwendet werden. Auch unser interaktives Query Builder eignet sich hervorragend zur interaktiven Erstellung benutzerdefinierter Abfragen.

Mit Seitenumbruch

Bei der Methode search wird die Paginierung verwendet, wobei ein anpassbarer pageSize-Parameter zusammen mit dem 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 '{
"pageSize": 10,
"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 (LQL)

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 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 (LQL)

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'

Verändert

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 in einer einzigen Anfrage zwei gemeinsame Kampagnenbudgets 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 es aus der Ausgabe des vorherigen Schritts kopieren und einfügen.

BUDGET_ID=BUDGET_ID

Bei Ressourcen, die auf andere Ressourcen verweisen, erfolgt dies anhand des Ressourcennamens. Die unten erstellte Kampagne bezieht sich auf einen campaignBudget durch seinen als Stringwert vorhandenen Ressourcennamen.

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 mit update-Vorgängen aktualisieren. Im nächsten Beispiel wird eine vorhandene Kampagne verwendet. Sie können diese aus der 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 in der Anfrage, die als Aktualisierung angewendet werden sollen. Attribute, die im updateMask aufgeführt sind, aber nicht im Anfragetext vorhanden sind, werden für ein Objekt gelöscht. Attribute, die nicht im 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

Zum Entfernen von Objekten wird ihr Ressourcenname als remove-Vorgang angegeben.

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, 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 diese aus der Ausgabe des Creates-Beispiels kopieren und einfügen.

CAMPAIGN_ID=CAMPAIGN_ID

Die folgende Anfrage enthält zwei Vorgänge. Der erste Versuch, die Gebotsstrategie der angegebenen Kampagne zu ändern, und der nächste 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 Vorgänge unterschiedlichen Typs senden, um eine Folge 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 schlagen alle fehl, wenn ein einzelner Vorgang fehlschlägt.

In diesem Beispiel wird gezeigt, wie ein Kampagnenbudget, eine Kampagne, eine Anzeigengruppe und eine Anzeige zusammen als eine einzige Gruppe von Aktionen erstellt werden. Die einzelnen nachfolgenden Operationen hängen von der jeweils vorherigen ab. Wenn ein Vorgang 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 Vorgangssequenz 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. Die URL erfordert eine Verwaltungskonto--ID anstelle einer Kundenkonto-ID. 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'
}
}"

Barrierefreie 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 sollten 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ärdaten, z. B. ein Bild, werden als String codiert. Dazu wird die Base64-Standardcodierung mit Abstand verwendet. Es wird entweder die Standard- oder die URL-sichere Base64-Codierung mit oder ohne Padding akzeptiert.

In diesem Beispiel wird ein 1-Pixel-GIF codiert, damit das Beispiel prägnant bleibt. In der Praxis sind die data-Nutzlasten viel größer.

Verwenden Sie das Befehlszeilendienstprogramm base64 (Teil der GNU-Kerndienstprogramme), um ein 1-Pixel-GIF-Bild zu codieren.

base64 1pixel.gif

Der base64-codierte Wert wird als data-Attribut in einer API-Anfrage 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'
      }
    }
  }
]
}"