Uwierzytelnianie i autoryzacja

Podobnie jak inne interfejsy API Google, interfejs Google Ads API używa protokołu OAuth 2.0 do uwierzytelniania i autoryzacji. OAuth 2.0 umożliwia aplikacji klienckiej interfejsu Google Ads API dostęp do konta Google Ads użytkownika bez konieczności obsługiwania i przechowywania jego danych logowania.

Model dostępu do Google Ads

Aby skutecznie korzystać z interfejsu Google Ads API, musisz wiedzieć, jak działa model dostępu do Google Ads. Zapoznaj się z przewodnikiem po modelu dostępu do Google Ads.

Przepływy pracy OAuth

Podczas pracy z interfejsem Google Ads API używa się 3 typowych procesów.

Przepływ konta usługi

Jest to zalecany przepływ pracy, jeśli nie wymaga on interakcji z człowiekiem. Ten proces wymaga wykonania kroku konfiguracji, w którym użytkownik dodaje konto usługi do swojego konta Google Ads. Aplikacja może następnie używać danych logowania konta usługi do zarządzania kontem Google Ads użytkownika. Aby to skonfigurować, utwórz i pobierz plik klucza JSON w konsoli Google Cloud, a następnie skopiuj plik google_ads_config.rb do katalogu domowego i zmodyfikuj go, aby określić lokalizację pliku klucza konta usługi (oraz opcjonalny adres e-mail użytkownika, pod którego chcesz się podszywać podczas korzystania z przekazywania dostępu w całej domenie Google Workspace):

# You can also authenticate using a service account. If "keyfile" is
# specified below, then service account authentication will be assumed and
# the above authentication fields ignored. Read more about service account
# authentication here:
# https://developers.google.com/google-ads/api/docs/oauth/service-accounts
c.keyfile = 'path/to/keyfile.json'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Jeśli nie chcesz przechowywać tych informacji w pliku i wolisz używać zmiennych środowiskowych, możesz ustawić GOOGLE_ADS_JSON_KEY_FILE_PATH (i opcjonalnie GOOGLE_ADS_IMPERSONATED_EMAIL):

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Możesz też przekazać ścieżkę pliku klucza konta usługi (i opcjonalny adres e-mail, pod który chcesz się podszyć) automatycznie w czasie działania:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

Możesz też użyć gemu googleauth, aby utworzyć dane logowania konta usługi i przekazać credentials.updater_proc do config.authentication:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file.
key_file = '/path/to/your/service-account-key.json'

# Define the scopes needed for the Google Ads API.
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials.
credentials = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

Więcej informacji znajdziesz w przewodniku po przepływie pracy konta usługi.

Proces uwierzytelniania jednego użytkownika

Możesz użyć tego przepływu pracy, jeśli nie możesz korzystać z kont usługi. Ten przepływ pracy wymaga 2 czynności konfiguracyjnych:

  1. Przyznaj jednemu użytkownikowi dostęp do wszystkich kont, którymi chcesz zarządzać za pomocą interfejsu Google Ads API. Często stosowanym podejściem jest przyznanie użytkownikowi dostępu do konta menedżera interfejsu Google Ads API i połączenie wszystkich kont Google Ads z tym kontem menedżera.
  2. Użytkownik uruchamia narzędzie wiersza poleceń, np. narzędzie wiersza poleceń Google Cloud lub przykładowy kod GenerateUserCredentials, aby upoważnić Twoją aplikację do zarządzania wszystkimi jego kontami Google Ads w jego imieniu.

Dane logowania OAuth 2.0 można skonfigurować dla Ruby, kopiując plik google_ads_config.rb do katalogu domowego i modyfikując go tak, aby zawierał identyfikator klienta, klucz klienta i token odświeżania:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

Klient automatycznie odczytuje plik konfiguracji z katalogu domowego, jeśli zostanie utworzony bez argumentów:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Jeśli wolisz przechowywać plik w innym miejscu, możesz utworzyć instancję klienta, przekazując ścieżkę do miejsca, w którym przechowujesz ten plik:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Jeśli nie chcesz przechowywać tych informacji w pliku i wolisz używać zmiennych środowiskowych, możesz ustawić każdą z nich:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Możesz też przekazywać te informacje automatycznie w czasie działania aplikacji:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

Więcej informacji znajdziesz w przewodniku po procesie uwierzytelniania pojedynczego użytkownika.

Proces uwierzytelniania wielu użytkowników

Jest to zalecany proces, jeśli aplikacja umożliwia użytkownikom logowanie się i autoryzowanie aplikacji do zarządzania kontami Google Ads w ich imieniu. Aplikacja tworzy dane uwierzytelniające użytkownika OAuth 2.0 i nimi zarządza. Ten przepływ pracy można skonfigurować podobnie jak przepływ pracy dla jednego użytkownika, podając również parametr login_customer_id.

Zalecamy użycie pliku konfiguracji. Skopiuj plik google_ads_config.rb do katalogu głównego i zmodyfikuj go, aby zawierał identyfikator klienta, tajny klucz klienta, token odświeżania i identyfikator klienta:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. If you need to use different values for this field, then
# make sure to fetch a new copy of the service after each time you change the
# value.
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

Klient automatycznie odczytuje plik konfiguracji z katalogu domowego, jeśli zostanie utworzony bez argumentów:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Jeśli wolisz przechowywać plik w innym miejscu, możesz utworzyć instancję klienta, przekazując ścieżkę do miejsca, w którym przechowujesz ten plik:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Jeśli nie chcesz przechowywać tych informacji w pliku i wolisz używać zmiennych środowiskowych, możesz ustawić każdą z nich:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

Możesz też przekazywać te informacje automatycznie w czasie działania aplikacji:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Więcej informacji znajdziesz w przewodniku po przepływie pracy uwierzytelniania wielu użytkowników. Biblioteka klienta Ruby zawiera przykładowy kod do celów referencyjnych. Przykładowy kod wiersza poleceń GenerateUserCredentials pokazuje, jak uzyskać uwierzytelnianie użytkownika w czasie działania, aby zarządzać jego kontami Google Ads w jego imieniu. Możesz użyć tego przykładowego kodu jako odniesienia do tworzenia aplikacji komputerowych, które wymagają uwierzytelniania użytkownika.

Zarządzanie wieloma kontami

Użytkownicy często zarządzają więcej niż jednym kontem Google Ads, korzystając z bezpośredniego dostępu do kont lub z konta menedżera Google Ads. Biblioteka klienta Ruby zawiera te przykłady kodu, które pokazują, jak obsługiwać takie przypadki:

  1. Przykładowy kod GetAccountHierarchy pokazuje, jak pobrać listę wszystkich kont na koncie menedżera Google Ads.
  2. Przykładowy kod w języku ListAccessibleCustomers pokazuje, jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp. Tych kont można następnie używać jako prawidłowych wartości ustawienia login_customer_id.

Domyślne uwierzytelnianie aplikacji

Biblioteka klienta Ruby (w wersji 36.1.0 lub nowszej) obsługuje też uwierzytelnianie za pomocą domyślnych danych uwierzytelniających aplikacji (ADC). Umożliwia ustawienie domyślnych danych logowania dla aplikacji bez konieczności konfigurowania informacji OAuth 2.0 w konfiguracji aplikacji.

Jest to szczególnie przydatne w przypadku programowania lokalnego lub programowania z użyciem różnych interfejsów API Google, ponieważ możesz ponownie używać tych samych danych logowania, o ile mają one dostęp do wymaganych zakresów OAuth 2.0.

W przypadku interfejsu Google Ads API upewnij się, że domyślne uwierzytelnianie aplikacji ma dostęp do zakresu OAuth 2.0 https://www.googleapis.com/auth/adwords.

Aby użyć domyślnego uwierzytelniania aplikacji, użyj narzędzia wiersza poleceń Google Cloud i uwierzytelnij się na potrzeby ADC:

gcloud auth application-default login

To polecenie otwiera przeglądarkę, aby dokończyć proces uwierzytelniania na koncie Google. Po autoryzacji przechowuje dane logowania w standardowej lokalizacji. Następnie musisz zaktualizować aplikację, aby używała ADC.

Skopiuj plik google_ads_config.rb do katalogu domowego i ustaw use_application_default_credentials na true:

# You can also authenticate using Application Default Credentials (ADC).
# To understand how ADC discovers credentials in a given environment, see:
# https://developers.google.com/identity/protocols/application-default-credentials
c.use_application_default_credentials = true

Jeśli nie chcesz przechowywać tych informacji w pliku i wolisz używać zmiennych środowiskowych, możesz ustawić GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Możesz też przekazywać informacje automatycznie w czasie działania. Podczas inicjowania klienta w kodzie Ruby ustaw config.use_application_default_credentials = true i nie podawaj jawnych danych uwierzytelniających OAuth 2.0. Biblioteka automatycznie wykrywa i używa danych logowania skonfigurowanych przez narzędzie wiersza poleceń Google Cloud:

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = 'YOUR_LOGIN_CUSTOMER_ID'

  # Do NOT include client_id, client_secret, or refresh_token here.
end

Więcej informacji o dostępnych opcjach konfigurowania biblioteki klienta w Ruby znajdziesz na stronie konfiguracji.