Proces uwierzytelniania jednego użytkownika

Uwaga: w tym przewodniku zakładamy, że znasz model dostępu do Google Ads. Jeśli nie, zapoznaj się z przewodnikiem Model dostępu do Google Ads, aby poznać te pojęcia. Dane logowania OAuth skonfiguruj w tym samym projekcie w chmurze Google, w którym włączono interfejs Google Ads API i w którym zażądano odpowiedniego poziomu dostępu do interfejsu API, aby interfejs Google Ads API działał prawidłowo.

Uwaga: Google zaleca korzystanie z przepływu pracy konta usługi zamiast przepływu pracy uwierzytelniania pojedynczego użytkownika. Używaj przepływu pracy uwierzytelniania pojedynczego użytkownika tylko wtedy, gdy nie można użyć kont usługi.

Podobnie jak w przypadku przepływu pracy konta usługi, przepływ uwierzytelniania pojedynczego użytkownika korzysta z funkcji autoryzacji i zarządzania użytkownikami oferowanych przez interfejs Google Ads, aby przyznać aplikacji dostęp do wszystkich niezbędnych kont. Ten proces uwierzytelniania składa się z 2 etapów:

• Przyznajesz jednemu użytkownikowi dostęp do wszystkich kont Google Ads, którymi ma zarządzać aplikacja.
• Użytkownik autoryzuje aplikację do zarządzania jego kontami Google Ads w jego imieniu, przyznając jej dostęp do wszystkich kont Google Ads.

Ponieważ jest tylko jeden użytkownik, możesz zamiast tworzyć własny proces uwierzytelniania użytkownika OAuth 2.0 korzystać z narzędzi takich jak gcloud CLI lub przykładowy kod GenerateUserCredential.

Podobny przypadek użycia tego przepływu pracy występuje, gdy do kont można uzyskać dostęp za pomocą kilku loginów użytkowników (np. 3–4 użytkowników), więc nakład pracy związany z opracowaniem pełnego procesu uwierzytelniania OAuth dla wielu użytkowników nie jest uzasadniony w porównaniu z nakładem pracy potrzebnym do uzyskania autoryzacji dla 3–4 użytkowników za pomocą narzędzia wiersza poleceń, takiego jak gcloud CLI.

Wady

W porównaniu z przepływem pracy dotyczącym konta usługi ten przepływ ma kilka wad:

1. Proces uwierzytelniania użytkownika wymaga utworzenia w konsoli Google Cloud identyfikatora klienta i tajnego klucza klienta OAuth 2.0, co wymaga więcej kroków konfiguracji niż utworzenie konta usługi i klucza.
2. Jeśli autoryzowany użytkownik opuści zespół lub firmę, aplikacja może przestać działać, jeśli usuniesz go z kont lub wyłączysz jego konto. Konta usługi nie są powiązane z poszczególnymi użytkownikami, więc to ryzyko jest wyeliminowane.
3. Użytkownik autoryzujący konto Google Ads powinien włączyć klucze dostępu na swoim koncie Google, aby chronić je przed przejęciem z powodu słabego zabezpieczenia, złośliwego oprogramowania lub phishingu. Konta usługi nie wymagają włączenia kluczy dostępu i są mniej podatne na ten problem, ponieważ niektóre z tych sposobów ataku nie mają do nich bezpośredniego zastosowania.

Generowanie danych logowania

Uwaga: w tym przewodniku podczas tworzenia danych uwierzytelniających OAuth używamy aplikacji na komputer jako typu aplikacji OAuth, ponieważ najlepiej współpracuje ona z interfejsem wiersza poleceń gcloud. W przypadku procesu uwierzytelniania pojedynczego użytkownika ten typ aplikacji OAuth może być używany niezależnie od rodzaju tworzonej aplikacji. Jeśli zamiast tego wybierzesz Aplikacja internetowa, musisz użyć OAuth 2.0 Playground, aby wygenerować token odświeżania. Instrukcje znajdziesz w tym filmie.

1. Skonfiguruj ekran zgody OAuth w aplikacji i dodaj https://www.googleapis.com/auth/adwords jako zakres OAuth 2.0. Więcej informacji znajdziesz w artykule Konfigurowanie ekranu zgody OAuth.

2. Utwórz identyfikator klienta i tajny klucz klienta, postępując zgodnie z instrukcjami. Po utworzeniu klienta OAuth 2.0 pobierz plik JSON klienta, klikając przycisk Pobierz JSON w oknie potwierdzenia. Zapisz plik jako credentials.json.

3. Wskaż konto użytkownika, które ma dostęp do wszystkich kont Google Ads, którymi chcesz zarządzać za pomocą aplikacji. Jeśli brakuje dostępu do niektórych kont, przyznaj dostęp do konta temu użytkownikowi.

4. Pobierz i zainstaluj gcloud CLI. Po zainstalowaniu sprawdź, czy narzędzie działa prawidłowo, uruchamiając polecenie gcloud version w wierszu poleceń. Dane wyjściowe wyglądają podobnie do tych:

   gcloud version

   Google Cloud SDK 492.0.0
   alpha 2024.09.06
   beta 2024.09.06
   bq 2.1.8
   bundled-python3-unix 3.11.9
   core 2024.09.06
   enterprise-certificate-proxy 0.3.2
   gcloud-crc32c 1.0.0
   

5. Wygeneruj token odświeżania OAuth 2.0, uruchamiając narzędzie gcloud CLI z plikiem credentials.json z poprzedniego kroku. Przekazanie parametru --client-id-filejest wymagane, aby token odświeżania został wydany w ramach projektu w Konsoli interfejsów API Google, a nie domyślnego projektu gcloud CLI:

   gcloud auth application-default login \
     --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
     --client-id-file=PATH_TO_CREDENTIALS_JSON

6. Polecenie gcloud otwiera okno logowania na konto Google w nowym oknie przeglądarki i przeprowadza Cię przez proces uwierzytelniania OAuth 2.0. Zaloguj się jako użytkownik wybrany w poprzednich krokach. Jeśli Twoja aplikacja jest niezweryfikowana, może pojawić się ekran z ostrzeżeniem. W takich przypadkach możesz bezpiecznie kliknąć link Zaawansowane i opcję Otwórz stronę PROJECT_NAME (niebezpieczną).

7. Po sprawdzeniu zakresów kliknij przycisk Dalej, aby przyznać uprawnienia. Przeglądarka przechodzi na stronę https://cloud.google.com/sdk/auth_success, co oznacza, że uwierzytelnianie zakończyło się powodzeniem. Na stronie wyświetli się ten komunikat:

   Authorization code granted. Close this tab.

   Polecenie gcloud wyświetla ten komunikat:

   Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]
   

   Otwórz plik application_default_credentials.json. Jego zawartość jest podobna do tej:

   {
     "account": "",
     "client_id": "******.apps.googleusercontent.com",
     "client_secret": "******",
     "refresh_token": "******",
     "type": "authorized_user",
     "universe_domain": "googleapis.com"
   }
   

Konfiguracja biblioteki klienta

Wybierz kartę odpowiadającą Twojemu językowi programowania, aby uzyskać instrukcje konfigurowania biblioteki klienta. Jeśli upoważniony użytkownik uzyskuje dostęp do kont klientów za pomocą konta menedżera Google Ads (MCK), ustaw wartość login-customer-id (lub loginCustomerId) na 10-cyfrowy identyfikator klienta tego konta menedżera bez łączników.

Java

Skonfiguruj w pliku ads.properties te klucze.

api.googleads.clientId=INSERT_OAUTH2_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Więcej opcji znajdziesz w przewodniku po konfiguracji.

.NET

Ustaw dane logowania OAuth 2.0 w instancji GoogleAdsConfig i użyj ich do zainicjowania obiektu GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
};
GoogleAdsClient client = new GoogleAdsClient(config);

Więcej opcji znajdziesz w przewodniku po konfiguracji.

Python

Skonfiguruj w pliku google-ads.yaml te klucze.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
use_proto_plus: True

Więcej opcji znajdziesz w przewodniku po konfiguracji.

PHP

Skonfiguruj te klucze w google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

Więcej opcji znajdziesz w przewodniku po konfiguracji.

Ruby

Skonfiguruj te klucze w pliku google_ads_config.rb.

Google::Ads::GoogleAds::Config.new do |c|
  c.client_id = 'INSERT_OAUTH2_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Więcej opcji znajdziesz w przewodniku po konfiguracji.

Perl

Skonfiguruj w pliku googleads.properties te klucze.

clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Więcej opcji znajdziesz w przewodniku po konfiguracji.

curl

Zacznij od pobrania tokena dostępu OAuth 2.0 za pomocą klienta HTTP. W tym przewodniku używamy polecenia curl.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://oauth2.googleapis.com/token

Tokena dostępu możesz używać w wywołaniach interfejsu API. W tym przykładzie pokazujemy, jak wygenerować raport kampanii za pomocą metody GoogleAdsService.SearchStream, aby pobrać kampanie na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.

curl -i -X POST \
  https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

Zawartość pliku query.json jest następująca:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}