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 przykłady przedstawione w tym dokumencie należy skopiować i wkleić do powłoki bash za pomocą polecenia curl.

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

Zmienne środowiskowe

Wpisz dane logowania i identyfikatory zgodnie z instrukcjami, a potem skopiuj je i wklej w terminalu, aby skonfigurować zmienne środowiskowe używane w kolejnych przykładach. W przewodniku Autoryzacja znajdziesz instrukcje generowania tokena dostępu OAuth 2.0.

API_VERSION="20"
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 dotychczasowych 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 dwie funkcje Mutates – Creates examples utworzą 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 zapytań niestandardowych.

Z podziałem na strony

Metoda search korzysta z paginacji ze stałym rozmiarem strony wynoszącym 10 000 elementów, a parametr page_token jest określany wraz z parametrem 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'

### Strumieniowanie 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'

Mutates

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

Tworzy

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

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żyto BUDGET_ID istniejącego 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 robią to za pomocą nazwy zasobu. Kampania utworzona w poniższym przykładzie odwołuje się do campaignBudget za pomocą nazwy zasobu w formie 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ż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 listy atrybutów JSON oddzielonych przecinkami, które powinny znajdować się w żądaniu i zostać zastosowane jako aktualizacja. Atrybuty wymienione w parametrze updateMask, ale nieobecne w treści żądania, są usuwane z obiektu. Atrybuty niewymienione 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 jest wiele operacji, możesz podać partialFailure. Jeśli true, operacje są wykonywane, a nieprawidłowe operacje zwracają 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żyto istniejącej kampanii. Możesz skopiować i wkleić dane wyjściowe z przykładu tworzenia.

CAMPAIGN_ID=CAMPAIGN_ID

To żądanie zawiera 2 operacje. Pierwsza próba zmiany strategii ustalania stawek w podanej kampanii, a druga – usunięcia kampanii z nieprawidłowym identyfikatorem. Druga operacja powoduje błąd (identyfikator kampanii jest nieprawidłowy), a ponieważ parametr partialFailure ma wartość false, pierwsza operacja też 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 "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'
  }
]
}"

Pogrupowane operacje

Metoda googleAds:mutate umożliwia wysyłanie grup operacji z wieloma typami zasobów. Możesz wysyłać wiele operacji różnych typów, aby połączyć w łańcuch sekwencję operacji, które powinny być wykonywane jako grupa. Zestaw operacji zakończy się powodzeniem, jeśli żadna operacja nie zakończy się niepowodzeniem, lub niepowodzeniem, jeśli jakakolwiek pojedyncza operacja zakończy 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 jedna z nich się nie powiedzie, nie powiedzie się cała grupa operacji.

Liczby całkowite ujemne (-1, -2, -3) są używane jako zmienne 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

Możesz tworzyć konta, wyświetlać listę kont, do których masz dostęp, i przesyłać zasoby binarne.

Tworzenie kont

Utwórz nowe konta, korzystając z metody createCustomerClient. Pamiętaj, że adres URL wymaga identyfikatora konta menedżera zamiast 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 "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, do których masz dostęp

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 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 komponentó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 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 niego.

W tym przykładzie kodujemy GIF-a o rozmiarze 1 piksela, aby był jak najkrótszy. W praktyce ładunki data są znacznie większe.

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

base64 1pixel.gif

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

curl

GAQL

Mutates

Tworzy

Aktualizacje

Usuń

Częściowe niepowodzenia

Pogrupowane operacje

Zarządzanie kontem

Tworzenie kont

Wyświetlanie listy kont, do których masz dostęp

Przesyłanie komponentów binarnych

Przykłady