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ść żądania 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 strona referencyjna dla GoogleAdsService.Search zawiera treść żądania i odpowiedzi dla metody Search.

Wymagania wstępne

Wszystkie pokazane 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) oraz konta menedżera Google Ads zawierającego co najmniej 1 konto klienta.

Zmienne środowiskowe

Wpisz dane logowania i identyfikatory kont, jak pokazano na ilustracji, 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 po autoryzacji.

API_VERSION="26"
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 działają w przypadku istniejących 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 sposób pokazany poniżej.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

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

Szukaj

Przewodnik Query Cookbook zawiera wiele przykładowych 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 interaktywne narzędzie do tworzenia zapytań to również świetne źródło informacji o interaktywnym tworzeniu niestandardowych zapytań.

Z podziałem na strony

Metoda search używa podziału na strony o stałym rozmiarze 10 000 elementów i parametru page_token określonego 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 "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 "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

W jednym żądaniu JSON można wysłać wiele operacji mutacji (create, update lub remove), wypełniając tablicę operations.

Tworzy

W tym przykładzie tworzone są 2 budżety kampanii wspólnych w ramach jednego żądania.

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

W następnym przykładzie użyto BUDGET_ID istniejącego budżetu kampanii. Możesz go skopiować i wkleić z danych wyjściowych z 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 elementu 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 "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

Zaktualizuj atrybuty istniejących obiektów za pomocą operacji update. W następnym przykładzie używamy istniejącej kampanii. Możesz skopiować i wkleić dane wyjściowe z poprzedniego kroku.

CAMPAIGN_ID=CAMPAIGN_ID

Wszystkie aktualizacje wymagają pola updateMask, czyli rozdzielonej przecinkami listy atrybutów JSON, które powinny znajdować się w żądaniu i zostać zastosowane jako aktualizacja. Atrybuty wymienione w updateMask, ale nieobecne w treści żądania, są usuwane z obiektu. Atrybuty, które nie są wymienione w updateMask, ale są 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 "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 określenie nazwy ich 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 "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 jest wiele operacji, możesz opcjonalnie określić partialFailure. Jeśli ustawisz wartość true, prawidłowe operacje zostaną wykonane, a nieprawidłowe zwrócą błędy. Jeśli false, wszystkie operacje w żądaniu zakończą się powodzeniem tylko wtedy, gdy wszystkie będą prawidłowe.

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

CAMPAIGN_ID=CAMPAIGN_ID

Poniższe żądanie zawiera 2 operacje. Pierwsza próbuje zmienić strategię ustalania stawek w podanej kampanii, a druga próbuje usunąć kampanię o nieprawidłowym identyfikatorze. Ponieważ druga operacja powoduje błąd (identyfikator kampanii jest nieprawidłowy), a parametr partialFailure ma wartość false, pierwsza operacja również się nie powiedzie, a strategia ustalania stawek w 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 "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 pogrupowane

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ć w łańcuch sekwencję operacji, które powinny zostać wykonane jako grupa. Zestaw operacji zakończy się powodzeniem, jeśli żadna operacja nie zakończy się niepowodzeniem, lub wszystkie zakończą się niepowodzeniem, jeśli jakakolwiek pojedyncza operacja zakończy się niepowodzeniem.

Ten przykład pokazuje, jak utworzyć budżet kampanii, kampanię, grupę reklam i reklamę w ramach jednego zestawu działań. Każda kolejna operacja zależy od poprzedniej. Jeśli jedna z nich się nie powiedzie, cała grupa operacji zakończy się niepowodzeniem.

Liczby całkowite ujemne (-1, -2, -3) są używane jako obiekty zastępcze w nazwach zasobów i są wypełniane dynamicznie 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 "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 kont

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

Użyj prostego żądania GET do metody listAccessibleCustomers, aby uzyskać listę kont Google Ads dostępnych za pomocą danego tokena dostępu OAuth 2.0. 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 "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, takie jak obraz, są kodowane jako ciąg znaków przy użyciu standardowego kodowania Base64 z dopełnieniem. Akceptowane jest standardowe kodowanie Base64 lub kodowanie Base64 bezpieczne dla adresów URL, z dopełnieniem lub bez.

W tym przykładzie kodowany jest GIF o rozmiarze 1 piksela, aby zachować zwięzłość. W praktyce ładunki data są znacznie większe.

Użyj narzędzia wiersza poleceń base64 (część podstawowych narzędzi GNU), aby zakodować obraz GIF o rozmiarze 1 piksela.

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

Tworzy

Aktualizacje

Usuń

Częściowe niepowodzenia

Operacje pogrupowane

Zarządzanie kontem

Tworzenie kont

Wyświetlanie listy dostępnych kont

Przesyłanie zasobów binarnych

Przykłady