Beispiele

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

Vorbereitung

Alle folgenden Beispiele sollen in ein Bash-Verfahren kopiert und eingefügt werden. curl-Befehl.

Sie benötigen außerdem ein Entwickler-Token, testen Sie Kontozugriff zulässig ist und Google Ads-Verwaltungskonto mit mindestens einem Kundenkonto.

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

Umgebungsvariablen

Geben Sie unten die Anmeldedaten und IDs für das Konto ein und kopieren Sie sie in Ihr um die in den nachfolgenden Beispielen verwendeten Umgebungsvariablen zu konfigurieren. Im Autorisierungsleitfaden finden Sie eine Anleitung zum Erstellen eines OAuth 2.0-Zugriffstoken.

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 haben, die in diesen Beispielen verwendet werden sollen, geben Sie sie unten ein.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Andernfalls wird mit den beiden Optionen Mutates – Erstellt Beispiele ein neues Budget erstellt. und Kampagne.

Suchen

Der Leitfaden Query Cookbook enthält viele die den Standardbildschirmen von Google Ads entsprechen und mit die in diesem Leitfaden verwendet werden. Unsere interaktive Abfrage Website-Builder auch eine großartige Ressource zum interaktiven Erstellen benutzerdefinierter Abfragen.

Mit Seitenumbruch

Die Methode search verwendet Paginierung mit einer festen Seitengröße von 10.000 Elementen und Eine page_token, die neben query angegeben ist.

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. Somit wird der Das Feld pageSize wird 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

Es können mehrere mutate-Vorgänge (create, update oder remove) in einem einzelnen JSON-Anfragetext durch Ausfüllen des operations-Arrays.

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. können Sie aus der Ausgabe des vorherigen Schritts kopieren und einfügen.

BUDGET_ID=BUDGET_ID

Ressourcen, die auf andere Ressourcen verweisen, Ressourcenname. Die unten erstellte Kampagne verweist auf einen campaignBudget durch seinen Ressourcennamen mit Stringwert.

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. Die nächste Beispiel: Eine bestehende Kampagne wird verwendet. können Sie aus der vorherigen Liste die Ausgabe des Schritts.

CAMPAIGN_ID=CAMPAIGN_ID

Alle Updates erfordern ein updateMask-Feld, eine durch Kommas getrennte Liste von welche JSON-Attribute in der Anfrage enthalten sein sollen, aktualisieren. Attribute, die in updateMask aufgeführt, aber nicht in der Anfrage vorhanden sind Textkörper aus einem Objekt gelöscht werden. Attribute, die nicht in der updateMask aufgeführt sind, aber vorhanden sind im Anfragetext, 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 einzigen Anfrage enthalten sind, geben Sie optional an. partialFailure Bei true werden erfolgreiche Vorgänge ausgeführt und Bei ungültigen Vorgängen werden Fehler zurückgegeben. Bei false werden alle Vorgänge in der Anfrage wenn und nur wenn sie gültig sind.

Im nächsten Beispiel wird eine vorhandene Kampagne verwendet. können Sie aus dem Menü Beispielausgabe erstellt:

CAMPAIGN_ID=CAMPAIGN_ID

Die folgende Anfrage enthält zwei Vorgänge. Der erste Versuch, Gebotsstrategie der angegebenen Kampagne zu erstellen, und in der nächsten wird versucht, eine Kampagne mit einer ungültigen ID. Da der zweite Vorgang zu einem Fehler führt (der Kampagnen-ID ungültig) ist und weil partialFailure auf false gesetzt ist, wird der schlägt auch die erste Operation fehl und die Gebotsstrategie der 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 unterschiedliche Ressourcentypen. Sie können viele Vorgänge unterschiedlicher Typen an eine Abfolge von Operationen verketten, die als Gruppe ausgeführt werden sollten. Die Gruppe von Vorgängen ist erfolgreich, wenn kein Vorgang fehlschlägt oder alle scheitern, falls vorhanden. einzelner Vorgang schlägt fehl.

In diesem Beispiel wird gezeigt, wie Sie ein Kampagnenbudget, eine Kampagne, eine Anzeigengruppe und Anzeigen zusammen als eine Reihe von Aktionen. Jeder aufeinanderfolgende Vorgang hängt davon ab, auf dem vorherigen. Wenn einer fehlschlägt, schlägt die gesamte Gruppe von Vorgängen fehl.

Negative Ganzzahlen (-1, -2, -3) werden als Platzhalter in der Ressource verwendet. Namen und werden zur Laufzeit dynamisch mit den Ergebnissen der Sequenz ausgefüllt. der Betriebsabläufe.

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 die ID eines Verwaltungskontos anstelle einer Kundenkonto-ID. Ein neuer Kunde wird im Verwaltungskonto 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 Methode listAccessibleCustomers, um eine Liste abzurufen von Google Ads-Konten, auf die mit dem angegebenen OAuth 2.0-Zugriffstoken zugegriffen werden kann. Kein Manager oder Kundenkonto-IDs verwendet werden sollen.

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 verwendet Assets: Binärdaten, z. B. ein Bild, werden wie folgt codiert: String mit der standardmäßigen base64-Codierung mit Padding. Entweder Standard- oder URL-sichere Base64-Codierungen mit oder ohne Padding werden akzeptiert.

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

Verwenden Sie das Befehlszeilendienstprogramm base64 (Teil von GNU-Kerndienstprogramme) 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'
      }
    }
  }
]
}"