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 Search metody.

Wymagania wstępne

Wszystkie przedstawione tu przykłady można skopiować i wkleić do bash shell 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 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 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 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

Przewodnik Query Cookbook zawiera 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 interaktywnym 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 treści jednego żą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,
    }
  }
]
}"

Następny przykład używa parametru 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 tym 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. Następny przykład używa istniejącej kampanii. Możesz go skopiować i wkleić z danych wyjściowych poprzedniego kroku.

CAMPAIGN_ID=CAMPAIGN_ID

Wszystkie aktualizacje wymagają pola updateMask, czyli listy rozdzielonych przecinkami 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 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ć parametr partialFailure. Jeśli ma on wartość true, operacje, które się powiodły, są wykonywane, a operacje nieprawidłowe zwracają błędy. Jeśli ma on wartość false, wszystkie operacje w żądaniu zakończą się powodzeniem tylko wtedy, gdy wszystkie będą prawidłowe.

Następny przykład używa istniejącej kampanii. Możesz go skopiować i wkleić z danych wyjściowych przykładu Tworzenie przykładu.

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

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

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 programu 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ę 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 jest tworzone 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 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 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.

W tym przykładzie kodujemy GIF-a o wymiarach 1 x 1 piksel, aby skrócić przykład. W praktyce ładunki data są znacznie większe.

Aby zakodować obraz GIF o wymiarach 1 x 1 piksel, użyj narzędzia wiersza polecenia base64 (część narzędzi GNU core) .

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