Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Przykłady

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

Więcej szczegółowych przykładów kodu znajdziesz w repozytorium GitHub z przykładami kodu REST.

Aby wyświetlić treści żądań i odpowiedzi dla każdej metody interfejsu API, zapoznaj się z dokumentacją referencyjną dotyczącą konkretnych punktów końcowych usługi.

Na przykład na stronie referencyjnej dla GoogleAdsService.Search znajdziesz treści żądań i odpowiedzi dla metody Search.

Wymagania wstępne

Wszystkie przedstawione tu przykłady można skopiować i wkleić do powłoki bash za pomocą polecenia curl.

Potrzebujesz też projektu Google Cloud (wystarczy dostęp do konta testowego) i konta menedżera Google Ads, które zawiera co najmniej 1 konto klienta.

Zmienne środowiskowe

Wpisz dane logowania i identyfikatory konta w podany sposób, a następnie skopiuj je i wklej do terminala, aby skonfigurować zmienne środowiskowe używane w kolejnych przykładach. Instrukcje generowania tokena dostępu OAuth 2.0 znajdziesz w przewodniku dotyczącym autoryzacji.

API_VERSION="25"
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 działają w przypadku wcześniej 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 w podany sposób.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

W przeciwnym razie 2 przykłady Mutates – Creates utworzą nowy budżet i kampanię.

Szukaj

W przewodniku Query Cookbook znajdziesz wiele przykładów raportowania, które odpowiadają niektórym domyślnym ekranom Google Ads i działają z tymi samymi zmiennymi środowiskowymi co w tym przewodniku. Nasze interaktywne narzędzie do tworzenia zapytań to też świetne źródło informacji o tworzeniu niestandardowych zapytań.

Z podziałem na strony

Metoda search używa paginacji ze stałym rozmiarem strony wynoszącym 10 000 elementów i parametrem page_token określonym 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 strumieniowo 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 jednej treści żądania JSON, wypełniając tablicę operations.

Tworzenie

Ten przykład tworzy 2 budżety wspólne 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 używany jest parametr BUDGET_ID istniejącego budżetu kampanii. Możesz go skopiować i wkleić z danych wyjściowych poprzedniego kroku.

BUDGET_ID=BUDGET_ID

Zasoby, które odwołują się do innych zasobów, robią to za pomocą nazwy zasobu. Kampania utworzona w poniższym przykładzie odwołuje się do campaignBudget za pomocą nazwy zasobu w postaci 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

Aktualizuj atrybuty istniejących obiektów za pomocą operacji update. W następnym przykładzie używana jest istniejąca kampania. Możesz ją skopiować i wkleić z danych wyjściowych poprzedniego kroku.

CAMPAIGN_ID=CAMPAIGN_ID

Wszystkie aktualizacje wymagają pola updateMask, czyli listy atrybutów JSON oddzielonych przecinkami, które powinny znajdować się w żądaniu i zostać zastosowane jako aktualizacja. Atrybuty wymienione w updateMask, ale nieobecne w treści żądania, są czyszczone w obiekcie. Atrybuty niewymienione w 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'
  }
],
}"

Usuwanie

Obiekty są usuwane przez określenie 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

Gdy w jednym żądaniu znajduje się wiele operacji, możesz opcjonalnie określić partialFailure. Jeśli wartość to true, operacje, które się powiodły, zostaną wykonane, a operacje nieprawidłowe zwrócą błędy. Jeśli wartość to false, wszystkie operacje w żądaniu zakończą się powodzeniem tylko wtedy, gdy wszystkie będą prawidłowe.

W następnym przykładzie używana jest istniejąca kampania. Możesz ją skopiować i wkleić z danych wyjściowych przykładu Tworzenie.

CAMPAIGN_ID=CAMPAIGN_ID

To żądanie zawiera 2 operacje. Pierwsza próbuje zmienić strategię ustalania stawek podanej kampanii, a druga – usunąć kampanię z nieprawidłowym identyfikatorem. Ponieważ druga operacja powoduje błąd (identyfikator kampanii jest nieprawidłowy), a parametr partialFailure ma wartość false, pierwsza operacja też się nie powiedzie, a strategia ustalania stawek istnieją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 grupowe

Metoda googleAds:mutate obsługuje wysyłanie grup operacji z wieloma typami zasobów. Możesz wysłać wiele operacji różnych typów, aby połączyć sekwencję operacji, które mają zostać wykonane jako grupa. Zestaw operacji zakończy się powodzeniem, jeśli żadna operacja się nie powiedzie, lub wszystkie zakończą się niepowodzeniem, jeśli nie powiedzie się jakakolwiek operacja.

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 jedna się nie powiedzie, nie powiedzie się cała grupa operacji.

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

Możesz tworzyć konta, wyświetlać listę dostępnych kont i przesyłać zasoby binarne.

Tworzenie konta

Twórz nowe konta za pomocą metody createCustomerClient. Pamiętaj, że adres URL wymaga identyfikatora konta menedżera, a nie identyfikatora konta klienta. Nowe konto klienta zostanie utworzone na koncie menedżera.

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 dostępnych kont

Aby uzyskać listę kont Google Ads, do których masz dostęp za pomocą danego tokena dostępu OAuth 2.0, użyj prostego żądania GET do metody listAccessibleCustomers. W tym żądaniu nie należy używać identyfikatorów kont menedżera ani kont 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 Assets. Dane binarne, takie jak obraz, są kodowane jako ciąg znaków za pomocą standardowego kodowania base64 z dopełnieniem. Akceptowane jest standardowe kodowanie base64 lub kodowanie base64 bezpieczne dla adresów URL z dopełnieniem lub bez niego.

Ten przykład koduje GIF o rozmiarze 1 piksela, aby skrócić przykład. W praktyce ładunki data są znacznie większe.

Aby zakodować obraz GIF o rozmiarze 1 piksela, użyj narzędzia wiersza polecenia base64 (część narzędzi GNU coreutils).

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 Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Wymagania wstępne

Zmienne środowiskowe

Dodatkowe opcjonalne identyfikatory obiektów

Szukaj

Z podziałem na strony

curl

GAQL

Streaming

curl

GAQL

Mutacje

Tworzenie

Aktualizacje

Usuwanie

Częściowe niepowodzenia

Operacje grupowe

Zarządzanie kontem

Tworzenie konta

Wyświetlanie listy dostępnych kont

Przesyłanie zasobów binarnych

Przykłady