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 lub przechowywania informacji logowania użytkownika.
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 korzystania z interfejsu Google Ads API stosuje się 3 typy procesów.
Proces konta usługi
Jest to zalecany przepływ pracy, jeśli nie wymaga on interakcji z użytkownikiem. Ten przepływ pracy wymaga konfiguracji, w ramach której użytkownik dodaje konto usługi do swojego konta Google Ads. Aplikacja może wtedy 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 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, którego tożsamość ma być używana podczas korzystania z delegowania 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 wolisz nie przechowywać tych informacji w pliku i 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 konta, na które ma być przekazane uprawnienie do reprezentowania) programowo 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ć gema 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 na koncie usługi.
Proces uwierzytelniania jednego użytkownika
Ten przepływ pracy może być używany, jeśli nie możesz korzystać z kont usługi. Ten przepływ pracy wymaga 2 etapów konfiguracji:
- Udzielić jednemu użytkownikowi dostępu do wszystkich kont, którymi ma zarządzać za pomocą interfejsu Google Ads API. Często stosowanym rozwiązaniem 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.
- Użytkownik uruchamia narzędzie wiersza poleceń, np. narzędzie wiersza poleceń Google Cloud lub
GenerateUserCredentialsprzykładowy kod, aby autoryzować Twoją aplikację do zarządzania w jego imieniu wszystkimi kontami Google Ads.
Dane logowania OAuth 2.0 można skonfigurować w przypadku Ruby, kopiując plik
google_ads_config.rb do katalogu domowego
i modyfikując go tak, aby zawierał identyfikator klienta, tajny 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'
Jeśli klient zostanie utworzony bez argumentów, automatycznie odczyta plik konfiguracyjny z katalogu domowego:
client = Google::Ads::GoogleAds::GoogleAdsClient.new
Jeśli wolisz przechowywać plik w innym miejscu, możesz utworzyć instancję klienta, przekazując ścieżkę do tego pliku:
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ć informacje programowo w czasie działania:
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 przepływie pracy 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 jej do zarządzania ich kontami Google Ads w ich imieniu. Aplikacja tworzy dane logowania użytkownika OAuth 2.0 i nimi zarządza. Ten przepływ pracy można skonfigurować podobnie jak przepływ dla jednego użytkownika, podając też login_customer_id.
Zalecamy używanie pliku konfiguracji. Skopiuj plik google_ads_config.rb do katalogu domowego 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'
Jeśli klient zostanie utworzony bez argumentów, automatycznie odczyta plik konfiguracyjny z katalogu domowego:
client = Google::Ads::GoogleAds::GoogleAdsClient.new
Jeśli wolisz przechowywać plik w innym miejscu, możesz utworzyć instancję klienta, przekazując ścieżkę do tego pliku:
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ć informacje programowo w czasie działania:
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ład kodu wiersza poleceń GenerateUserCredentials pokazuje, jak uzyskać uwierzytelnianie użytkownika w czasie działania programu, aby zarządzać jego kontami Google Ads w jego imieniu. Ten przykład kodu możesz wykorzystać jako punkt odniesienia do tworzenia aplikacji na komputery, które wymagają uwierzytelnienia użytkownika.
Zarządzanie wieloma kontami
Użytkownik może zarządzać więcej niż 1 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:
GetAccountHierarchyPrzykład kodu pokazuje, jak pobrać listę wszystkich kont na koncie menedżera Google Ads.- W przykładzie kodu
ListAccessibleCustomerspokazujemy, jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp. Konta te mogą być następnie używane jako prawidłowe wartości ustawienialogin_customer_id.
Domyślne dane logowania aplikacji
Biblioteka klienta Ruby (w wersji 36.1.0 i nowszych) obsługuje też uwierzytelnianie za pomocą domyślnych danych logowania aplikacji (ADC). Umożliwia to ustawienie domyślnych danych logowania do aplikacji bez konieczności konfigurowania informacji OAuth 2.0 w konfiguracji aplikacji.
Jest to szczególnie przydatne w przypadku lokalnego tworzenia aplikacji lub tworzenia aplikacji korzystających z różnych interfejsów API Google, ponieważ możesz ponownie użyć 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 dane logowania aplikacji mają dostęp do https://www.googleapis.com/auth/adwordszakresu OAuth 2.0.
Aby użyć domyślnego uwierzytelniania aplikacji, użyj narzędzia wiersza poleceń Google Cloud i uwierzytelnij się w ADC:
gcloud auth application-default login
To polecenie otwiera przeglądarkę internetową, aby dokończyć proces uwierzytelniania na koncie Google. Po autoryzacji zapisuje dane logowania w standardowej lokalizacji. Następnie musisz zaktualizować aplikację, aby korzystać z 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 programowo w czasie działania programu. Podczas inicjowania klienta w kodzie Ruby ustaw config.use_application_default_credentials = true i nie podawaj jawnych danych logowania 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 Ruby znajdziesz na stronie konfiguracji.