Uwaga: przeglądasz dokumentację interfejsu REST interfejsu API. Większość oficjalnych bibliotek klienta używa gRPC. Więcej informacji znajdziesz we wprowadzeniu do REST.

Ta strona została przetłumaczona przez Cloud Translation API.

Przykłady

Ten przewodnik zawiera przykłady bezpośredniego wywoływania punktów końcowych REST bez użycia biblioteki klienta.

Wymagania wstępne

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

Potrzebujesz też tokenu programisty, wystarczy dostęp do konta testowego, a także konta menedżera Google Ads, na którym znajduje się co najmniej 1 konto klienta.

Zmienne środowiskowe

Wpisz poniżej dane logowania i identyfikatory kont, a następnie skopiuj je i wklej do terminala, aby skonfigurować zmienne środowiskowe używane w kolejnych przykładach. Przewodnik Autoryzacja zawiera instrukcje generowania tokena dostępu OAuth 2.0.

API_VERSION="17"
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 poniższych przykładów dotyczą istniejących budżetów lub kampanii. Jeśli masz identyfikatory istniejących obiektów, których możesz użyć w tych przykładach, wpisz je poniżej.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

W przeciwnym razie użycie 2 opcji Mutyfikacje – tworzy przykłady utworzy nowy budżet i kampanię.

Przewodnik Query Cookbook zawiera wiele przykładów raportowania, które odpowiadają niektórym z domyślnych ekranów Google Ads i działają z tymi samymi zmiennymi środowiskowymi, których użyto w tym przewodniku. Nasze interaktywne narzędzie do tworzenia zapytań jest też doskonałym narzędziem do interaktywnego tworzenia zapytań niestandardowych.

Z podziałem na strony

Metoda search korzysta z podziału na strony ze stałym rozmiarem strony wynoszącym 10 tys. elementów i z atrybutem page_token określonym obok 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}"
}'

Ocena 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'

Strumieniowanie

Metoda searchStream przesyła strumieniowo wszystkie wyniki w pojedynczej 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'
"
}'

Ocena 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

W jednej treści żądania JSON można wysłać wiele operacji mutacji (create, update lub remove), wypełniając tablicę operations.

Tworzy

W tym przykładzie tworzymy 2 budżety kampanii w jednym żądaniu.

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 wykorzystywana jest wartość BUDGET_ID obecnego budżetu kampanii. Możesz skopiować i wkleić dane wyjściowe z 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 elementu campaignBudget za pomocą nazwy zasobu z wartością ciągó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

Aktualizuj atrybuty istniejących obiektów za pomocą operacji update. W następnym przykładzie zastosowano istniejącą kampanię. Możesz skopiować i wkleić dane wyjściowe z poprzedniego kroku.

CAMPAIGN_ID=CAMPAIGN_ID

Wszystkie aktualizacje wymagają pola updateMask, w postaci oddzielonej przecinkami listy atrybutów JSON, które powinny znaleźć się w żądaniu, które należy zastosować jako aktualizację. Atrybuty wymienione w zasadzie updateMask, których nie ma w treści żądania, są czyszczone z obiektu. Atrybuty, których nie ma w tabeli updateMask, ale znajdują się 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, określając nazwę ich zasobu w 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}'
  }
],
}"

Niepowodzenia częściowe

Jeśli w jednym żądaniu znajduje się wiele operacji, możesz opcjonalnie określić partialFailure. Jeśli ustawiona jest wartość true, wykonywane są udane operacje, a nieprawidłowe operacje zwracają błędy. Jeśli zasada false, wszystkie operacje w żądaniu zakończą się tylko wtedy, gdy są prawidłowe.

W następnym przykładzie korzystasz z istniejącej kampanii. Możesz skopiować i wkleić dane wyjściowe z przykładu Twórz.

CAMPAIGN_ID=CAMPAIGN_ID

To żądanie zawiera 2 operacje. W pierwszej kolejności próbujemy zmienić strategię ustalania stawek w danej kampanii, a następnie usunąć kampanię z nieprawidłowym identyfikatorem. Ponieważ druga operacja zakończy się błędem (identyfikator kampanii jest nieprawidłowy), a pole partialFailure ma wartość false, pierwsza operacja też się nie powiedzie, a strategia ustalania stawek w bieżącej kampanii nie zostanie zaktualizowana.

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 zgrupowane

Metoda googleAds:mutate obsługuje wysyłanie grup operacji z wieloma typami zasobów. Możesz wysłać wiele operacji różnego typu, aby połączyć sekwencję operacji, które powinny zostać wykonane jako grupa. Zbiór operacji zakończy się niepowodzeniem, jeśli żadna z nich nie powiedzie się, lub gdy wszystkie operacje zakończą się niepowodzeniem.

Ten przykład pokazuje, jak utworzyć budżet kampanii, kampanię, grupę reklam i reklamę jako jeden zestaw działań. Każda kolejna operacja zależy od poprzedniej. Jeśli w jednym przypadku wystąpi błąd, cała grupa operacji zakończy się niepowodzeniem.

Ujemne liczby całkowite (-1, -2, -3) są używane jako symbole zastępcze w nazwach zasobów i są wypełniane dynamicznie w czasie działania wynikami 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

Utwórz nowe konta za pomocą metody createCustomerClient. Pamiętaj, że adres URL wymaga identyfikatora konta menedżera zamiast identyfikatora konta klienta. Pod kontem 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'
}
}"

Konta dostępne do wyświetlania informacji o produktach

Wyślij do metody listAccessibleCustomers proste żądanie GET, aby uzyskać listę kont Google Ads dostępnych przy użyciu danego tokena dostępu OAuth 2.0. W tej prośbie nie należy używać żadnych identyfikatorów konta menedżera ani konta klienta.

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 zasobów i zarządzania nimi. Dane binarne, np. obraz, są kodowane jako ciąg znaków przy użyciu standardowego kodowania base64 z dopełnieniem. Dopuszczalne jest standardowe lub bezpieczne w adresie URL kodowanie base64 z dopełnieniem lub bez niego.

W tym przykładzie koduje się GIF-a o szerokości 1 piksela, by zachować zwięzłość. W praktyce ładunki typu data są znacznie większe.

Zakoduj obraz GIF-a o rozdzielczości 1 piksela za pomocą narzędzia wiersza poleceń base64 (dostępnego w podstawowych narzędziach GNU).

base64 1pixel.gif

Wartość zakodowana w formacie base64 jest określana jako atrybut data w żądaniu 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'
      }
    }
  }
]
}"

Przykłady

Wymagania wstępne

Zmienne środowiskowe

Dodatkowe opcjonalne identyfikatory obiektów

Wyszukiwarka

Z podziałem na strony

cURL

Ocena GAQL

Strumieniowanie

cURL

Ocena GAQL

Mutacje

Tworzy

Aktualizacje

Usuń

Niepowodzenia częściowe

Operacje zgrupowane

Zarządzanie kontem

Tworzenie kont

Konta dostępne do wyświetlania informacji o produktach

Przesyłanie zasobów binarnych