Achtung:Sie lesen die Dokumentation für die REST-Schnittstelle der API. Die meisten unserer offiziellen Clientbibliotheken verwenden gRPC. Weitere Informationen

Diese Seite wurde von der Cloud Translation API übersetzt.

Beispiele

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

Vorbereitung

Alle hier gezeigten Beispiele sind dafür vorgesehen, mit dem Befehl curl in eine Bash-Shell kopiert und eingefügt zu werden.

Außerdem benötigen Sie ein Entwicklertoken (Testkontozugriff ist ausreichend) und ein Google Ads-Verwaltungskonto mit mindestens einem Kundenkonto.

Umgebungsvariablen

Geben Sie die Anmeldedaten und IDs des Kontos 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 Autorisierungsanleitung finden Sie eine Anleitung zum Generieren eines OAuth 2.0-Zugriffstokens.

API_VERSION="20"
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 vorhandenen 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_ID

Andernfalls werden mit den beiden Mutates - Creates examples ein neues Budget und eine neue Kampagne erstellt.

Suchen

Die Query Cookbook enthält viele Berichtsbeispiele, die einigen der Standardbildschirme von Google Ads entsprechen und mit denselben Umgebungsvariablen wie in dieser Anleitung funktionieren. Unser Tool zum interaktiven Erstellen von Abfragen ist ebenfalls eine gute Ressource, um benutzerdefinierte Abfragen interaktiv zu erstellen.

Mit Seitenumbruch

Die search-Methode verwendet die Paginierung mit einer festen Seitengröße von 10.000 Elementen und einem page_token, der 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 '{
"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. 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 einzelnen JSON-Anfragetext 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 im folgenden Beispiel erstellte Kampagne verweist über ihren String-Ressourcennamen 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 mit update-Vorgängen. Im nächsten Beispiel wird eine bestehende Kampagne verwendet. Sie können die Ausgabe des vorherigen Schritts kopieren und einfügen.

CAMPAIGN_ID=CAMPAIGN_ID

Für alle Aktualisierungen ist das Feld updateMask erforderlich. Es enthält 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 vorhanden sind, werden für ein Objekt gelöscht. Attribute, die nicht in der 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

Objekte werden entfernt, indem ihr Ressourcennamen 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, können Sie optional partialFailure angeben. Bei true werden erfolgreiche Vorgänge ausgeführt und bei ungültigen Vorgängen werden Fehler zurückgegeben. Wenn 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 des Creates-Beispiels kopieren und einfügen.

CAMPAIGN_ID=CAMPAIGN_ID

Die folgende Anfrage enthält zwei Vorgänge. Bei den ersten Versuchen wird die Gebotsstrategie der angegebenen Kampagne geändert. Beim nächsten Versuch wird eine Kampagne mit einer ungültigen ID entfernt. 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 unterschiedlicher Typen senden, um eine Abfolge von Vorgängen zu verketten, die als Gruppe ausgeführt werden sollen. Die Gruppe von Vorgängen ist erfolgreich, wenn kein Vorgang fehlschlägt. Sie schlägt fehl, wenn ein einzelner Vorgang fehlschlägt.

In diesem Beispiel wird gezeigt, wie Sie ein Kampagnenbudget, eine Kampagne, eine Anzeigengruppe und eine Anzeige als eine Reihe von Aktionen 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 zur Laufzeit dynamisch mit den Ergebnissen der Operationsfolge 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, auf zugängliche Konten zugreifen und binäre Assets hochladen.

Konten erstellen

Erstellen Sie neue Konten mit der Methode createCustomerClient. Für die URL ist die ID eines Verwaltungskontos und nicht die ID eines Kundenkontos erforderlich. 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'
}
}"

Berechtigte 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 IDs von Verwaltungs- oder Kundenkonten 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är-Assets hochladen

Die Methode assets:mutate wird zum Hochladen und Verwalten von Assets verwendet. Binärdaten, z. B. ein Bild, werden als String mit standardmäßiger Base64-Codierung mit Padding codiert. Es wird entweder die Standard-Base64-Codierung oder die URL-sichere Base64-Codierung mit oder ohne Auffüllung 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 Befehlszeilentool base64 (Teil der GNU Core Utilities), um ein 1-Pixel-GIF-Bild zu codieren.

base64 1pixel.gif

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

Zurück

Häufige Fehler

Weiter

Probieren Sie es jetzt aus!

Beispiele Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Vorbereitung

Umgebungsvariablen

Zusätzliche optionale Objekt-IDs

Suchen

Mit Seitenumbruch

curl

GAQL

curl

GAQL

Mutiert

Erstellt

Updates

Entfernen

Teilweise fehlgeschlagene Vorgänge

Gruppierte Vorgänge

Kontoverwaltung

Konten erstellen

Berechtigte Konten auflisten

Binär-Assets hochladen

Beispiele