Beispiele

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.

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

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'
      }
    }
  }
]
}"