Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Beispiele

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

Ausführlichere Codebeispiele finden Sie im GitHub-Repository mit REST-Codebeispielen.

Die Anfrage- und Antworttextkörper für die einzelnen API-Methoden finden Sie in der Referenzdokumentation für die jeweiligen Dienstendpunkte.

Auf der Referenzseite für GoogleAdsService.Search werden beispielsweise die Anfrage- und Antworttextkörper für die Methode Search angezeigt.

Vorbereitung

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

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

Umgebungsvariablen

Geben Sie die Kontoanmeldedaten und IDs wie gezeigt 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="26"
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 beziehen sich auf bereits vorhandene 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 wird mit den beiden Mutates – Creates-Beispielen ein neues Budget und eine neue Kampagne erstellt.

Suchen

Der Leitfaden Query Cookbook enthält viele Berichtsbeispiele, die einigen der Standardbildschirme von Google Ads entsprechen und mit denselben Umgebungsvariablen funktionieren, die in diesem Leitfaden verwendet werden. Unser interaktives Query Builder-Tool ist ebenfalls eine gute Ressource, um benutzerdefinierte Abfragen interaktiv zu erstellen.

Mit Seitenumbruch

Die Methode search verwendet die Paginierung mit einer festen Seitengröße von 10.000 Elementen und einem page_token, das 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 "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

Die Methode searchStream streamt alle Ergebnisse in einer einzigen Antwort. 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 "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'

Änderungen

Mehrere Mutate-Vorgänge (create, update oder remove) können in einem einzigen 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 "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 auf ein campaignBudget mit dem String-Wert des Ressourcennamens.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--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 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, eine durch Kommas getrennte Liste der JSON-Attribute, die in der Anfrage enthalten sein sollen und als Aktualisierung angewendet werden sollen. Attribute, die in der updateMask aufgeführt sind, aber nicht im Anfragetext enthalten sind, werden für ein Objekt gelöscht. Attribute, die nicht in der updateMask 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 "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 "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 eine einzelne Anfrage mehrere Vorgänge enthält, geben Sie optional partialFailure an. Wenn true, werden erfolgreiche Vorgänge ausgeführt und ungültige Vorgänge geben Fehler zurück. 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 aus dem Beispiel Erstellen kopieren und einfügen.

CAMPAIGN_ID=CAMPAIGN_ID

Die folgende Anfrage enthält zwei Vorgänge. Im ersten 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 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 "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 Gruppe von Vorgängen ist erfolgreich, wenn kein Vorgang fehlschlägt. Wenn ein einzelner Vorgang fehlschlägt, schlagen alle fehl.

In diesem Beispiel wird gezeigt, wie Sie ein Kampagnenbudget, eine Kampagne, eine Anzeigengruppe und eine Anzeige zusammen als eine Reihe von Aktionen erstellen. Jeder nachfolgende Vorgang hängt vom 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 aus der Abfolge 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 "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, zugängliche Konten auflisten und binäre Assets hochladen.

Konten erstellen

Erstellen Sie neue Konten mit der Methode createCustomerClient. Für die URL ist die ID eines Verwaltungskontos anstelle der 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 "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 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 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 "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

Binäre Assets hochladen

Die Methode assets:mutate wird zum Hochladen und Verwalten von Assets verwendet. Binärdaten wie Bilder werden als String mit Standard-Base64-Codierung mit Padding codiert. 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, 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-Dienstprogramme), um ein GIF-Bild mit 1 Pixel zu codieren.

base64 1pixel.gif

Der base64-codierte Wert wird in einer API-Anfrage als Attribut data angegeben.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \
--header "Content-Type: application/json" \
--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'
      }
    }
  }
]
}"

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

Streaming

curl

GAQL

Änderungen

Erstellt

Updates

Entfernen

Teilweise fehlgeschlagene Vorgänge

Gruppierte Vorgänge

Kontoverwaltung

Konten erstellen

Zugängliche Konten auflisten

Binäre Assets hochladen

Beispiele