Przykłady

Ten przewodnik zawiera przykłady wywoływania punktów końcowych REST bezpośrednio, bez korzystania z biblioteki klienta.

Wymagania wstępne

Wszystkie przykłady poniżej należy skopiować i wkleić do powłoki bash za pomocą polecenia curl.

Potrzebujesz też tokenu programisty, dostępu do konta testowego i konta menedżera Google Ads zawierającego co najmniej 1 konto klienta.

Ważne: w tych przykładach zakładamy, że dostęp do konta klienta (CUSTOMER_ID) ma użytkownik, który ma dostęp administracyjny do konta menedżera (MANAGER_CUSTOMER_ID), które bezpośrednio zarządza kontem klienta. Jeśli zamiast tego chcesz uzyskać dostęp bezpośrednio do konkretnego konta klienta, pomiń nagłówek login-customer-id lub nadaj mu tę samą wartość co nagłówkowi CUSTOMER_ID. Pamiętaj, że niektóre przykłady, np. tworzenie kont, wymagają konta menedżera.

Zmienne środowiskowe

Poniżej wpisz dane logowania i identyfikatory konta, a potem skopiuj je i wklej do terminala, aby skonfigurować zmienne środowiskowe używane w kolejnych przykładach. W przewodniku Autoryzacja znajdziesz instrukcje generowania tokena dostępu OAuth 2.0.

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

Dodatkowe opcjonalne identyfikatory obiektów

Niektóre z tych przykładów dotyczą już utworzonych budżetów lub kampanii. Jeśli masz identyfikatory istniejących obiektów, których chcesz użyć w tych przykładach, wpisz je poniżej.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

W przeciwnym razie 2 parametry Mutates – Creates examples tworzą nowy budżet i nową kampanię.

Szukaj

Przewodnik Query Cookbook zawiera wiele przykładów raportów, które odpowiadają niektórym domyślnym ekranom Google Ads i działają z tymi samymi zmiennymi środowiskowymi, które są używane w tym przewodniku. Nasze narzędzie do tworzenia interaktywnych zapytań to też świetne narzędzie do interaktywnego tworzenia zapytań niestandardowych.

Z podziałem na strony

Metoda search używa podziału na strony z stałym rozmiarem strony wynoszącym 10 tys. elementów i z uwzględnieniem parametru page_token zdefiniowanego obok parametru query.

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

Metoda searchStream przesyła wszystkie wyniki w jednej odpowiedzi, dlatego pole pageSize nie jest obsługiwane.

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'

Mutacje

Wiele operacji mutacji (create, update lub remove) można wysłać w jednym ciele żądania JSON, wypełniając tablicę operations.

Tworzy

W tym przykładzie w jednym żądaniu tworzone są 2 budżety kampanii wspólnej.

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

W następnym przykładzie użyjemy BUDGET_ID obecnego budżetu kampanii. Możesz go skopiować z wyników poprzedniego kroku.

BUDGET_ID=BUDGET_ID

Zasoby odwołujące się do innych zasobów używają do tego nazwy zasobu. Kampania utworzona poniżej odwołuje się do campaignBudget za pomocą nazwy zasobu o typie ciągu znaków.

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

Aktualizacje

Zmień atrybuty istniejących obiektów za pomocą operacji update. W następnym przykładzie użyjemy istniejącej kampanii. Możesz skopiować i wklejć dane z wyniku poprzedniego kroku.

CAMPAIGN_ID=CAMPAIGN_ID

Wszystkie aktualizacje wymagają pola updateMask, czyli listy oddzielonych przecinkami atrybutów JSON, które powinny zostać zastosowane jako aktualizacja. Atrybuty wymienione w elementach updateMask, ale nieobecne w ciele żądania, są wyczyszczone w obiekcie. Atrybuty nie wymienione w sekcji updateMask, ale obecne w treści żądania, są ignorowane.

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

Usuń

Obiekty są usuwane przez podanie ich nazwy zasobu jako operacji remove.

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

Częściowe niepowodzenia

Jeśli w jednym żądaniu występuje kilka operacji, opcjonalnie podaj parametr partialFailure. Jeśli true, operacje zakończone sukcesem są wykonywane, a nieprawidłowe operacje zwracają błędy. Jeśli false, wszystkie operacje w żądaniu są wykonywane tylko wtedy, gdy są prawidłowe.

W następnym przykładzie używamy istniejącej kampanii. Możesz skopiować i wkleić dane z wyjścia tworzenia.

CAMPAIGN_ID=CAMPAIGN_ID

Poniższe żądanie zawiera 2 operacje. Pierwszy próbuje zmienić strategię ustalania stawek w podanej kampanii, a drugi usuwa kampanię o nieprawidłowym identyfikatorze. Druga operacja kończy się błędem (identyfikator kampanii jest nieprawidłowy), a ustawienie partialFailure również powoduje błąd. W rezultacie pierwsza operacja również kończy się błędem, a strategia ustalania stawek obecnej kampanii nie zostanie zaktualizowana.false

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

Operacje grupowe

Metoda googleAds:mutate obsługuje wysyłanie grup operacji z wieloma typami zasobów. Możesz wysyłać wiele operacji różnych typów, aby połączyć sekwencję operacji, które powinny być wykonywane jako grupa. Zestaw operacji zakończy się sukcesem, jeśli żadna operacja nie zakończy się niepowodzeniem, lub wszystkie operacje zakończą się niepowodzeniem, jeśli dowolna pojedyncza operacja zakończy się niepowodzeniem.

Ten przykład pokazuje tworzenie budżetu kampanii, kampanii, grupy reklam i reklamy jako pojedynczego zestawu działań. Każda kolejna operacja zależy od poprzedniej. Jeśli jedna operacja się nie powiedzie, cała grupa operacji również się nie powiedzie.

Wartości całkowite ujemne (-1, -2, -3) są używane jako zastępniki w nazwach zasobów i są wypełniane dynamicznie w czasie wykonywania kodu za pomocą wyników sekwencji operacji.

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

Zarządzanie kontem

Tworzenie kont

tworzyć nowe konta za pomocą metody createCustomerClient. Pamiętaj, że w adresie URL musisz podać identyfikator konta menedżera, a nie identyfikator konta klienta. Na koncie menedżera zostanie utworzone nowe konto klienta.

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

Wyświetlanie listy kont, które mają dostęp

Aby uzyskać listę kont Google Ads dostępnych za pomocą danego tokena dostępu OAuth 2.0, wyślij prostą prośbę GET do metody listAccessibleCustomers. W tym żądaniu nie należy używać identyfikatorów kont menedżera ani klientów.

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}" \

Przesyłanie zasobów binarnych

Metoda assets:mutate służy do przesyłania komponentów i zarządzania nimi. Dane binarne, takie jak obraz, są kodowane jako ciąg znaków za pomocą standardowego kodowania base64 z wypełnieniem. Akceptowane są standardowe kodowania base64 i kodowania base64 obsługiwane w adresach URL z dopełnieniem lub bez niego.

W tym przykładzie kodujemy GIF o rozmiarze 1 piksel, aby zachować zwięzłość. W praktyce dane data są znacznie większe.

Użyj narzędzia wiersza poleceń base64 (należącego do podstawowych narzędzi GNU), aby zakodować obraz GIF o wymiarach 1 piksel.

base64 1pixel.gif

Wartość zakodowana w formacie base64 jest podawana jako atrybut data w żądaniu wysłanym do interfejsu API.

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