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 informacji logowania użytkownika.
Poznawanie modelu dostępu do Google Ads
Aby skutecznie korzystać z interfejsu Google Ads API, musisz zrozumieć, jak działa model dostępu do Google Ads. Zalecamy przeczytanie przewodnika po modelu dostępu do Google Ads.
Przepływy pracy OAuth
Podczas pracy z interfejsem Google Ads API używane są 3 typowe przepływy pracy.
Przepływ konta usługi
Jest to zalecany przepływ pracy, jeśli nie wymaga on interakcji z użytkownikiem. Ten przepływ pracy wymaga wykonania kroku konfiguracji, w którym użytkownik dodaje konto usługi do swojego konta Google Ads. Aplikacja może wtedy używać danych uwierzytelniających 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 adres e-mail użytkownika, którego chcesz personifikować:
# 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'
# 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ć odpowiednio zmienne GOOGLE_ADS_JSON_KEY_FILE_PATH i GOOGLE_ADS_IMPERSONATED_EMAIL.
export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"
Możesz też przekazać te informacje programowo w czasie działania, używając pakietu googleauth do utworzenia danych uwierzytelniających z pliku JSON konta usługi:
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 = Google::Auth::ServiceAccountCredentials.make_creds(
json_key_io: File.open(key_file),
scope: scopes
)
# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
config.developer_token = "YOUR_DEVELOPER_TOKEN"
# Inject the service account credentials
config.oauth2_client = credentials
end
Więcej informacji znajdziesz w przewodniku po przepływie pracy konta usługi dowiedz się więcej.
Przepływ uwierzytelniania pojedynczego użytkownika
Ten przepływ pracy może być używany, jeśli nie możesz korzystać z kont usług. Ten przepływ pracy wymaga wykonania 2 kroków konfiguracji:
- Przyznaj jednemu użytkownikowi dostęp do wszystkich kont, którymi chcesz zarządzać za pomocą interfejsu Google Ads API. Powszechnym 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ń, takie jak gcloud lub
GenerateUserCredentialsprzykładowy kod, aby autoryzować Twoją aplikację do zarządzania wszystkimi jego kontami Google Ads w jego imieniu.
Dane uwierzytelniające protokołu OAuth 2.0 można skonfigurować w Ruby, kopiując plik google_ads_config.rb do katalogu domowego i modyfikując go tak, aby zawierał token programisty, identyfikator klienta, tajny klucz klienta i token odświeżania:
# The developer token is required to authenticate that you are allowed to
# make API calls.
c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
# 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 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_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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ż przekazać te informacje programowo w czasie działania:
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
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 uwierzytelniania pojedynczego użytkownika.
Przepływ uwierzytelniania wielu użytkowników
Jest to zalecany przepływ pracy, jeśli Twoja aplikacja umożliwia użytkownikom logowanie się i autoryzowanie aplikacji do zarządzania ich kontami Google Ads w ich imieniu. Twoja aplikacja tworzy dane uwierzytelniające użytkownika OAuth 2.0 i zarządza nimi. Ten przepływ pracy można skonfigurować podobnie jak przepływ pojedynczego użytkownika, ale należy też określić login_customer_id.
Zalecamy używanie pliku konfiguracyjnego. Skopiuj plik google_ads_config.rb do katalogu domowego i zmodyfikuj go tak, aby zawierał token programisty, identyfikator klienta, klucz klienta, token odświeżania i identyfikator klienta:
# The developer token is required to authenticate that you are allowed to
# make API calls.
c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
# 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 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 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_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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ż przekazać te informacje programowo w czasie działania:
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
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 uwierzytelniania wielu użytkowników, aby dowiedzieć się więcej. Biblioteka klienta Ruby zawiera przykładowy kod do celów referencyjnych. GenerateUserCredentials to przykładowy kod wiersza poleceń, który 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 na komputery, które wymagają uwierzytelnienia użytkownika.
Co zrobić, jeśli użytkownik zarządza kilkoma 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 sobie radzić w takich przypadkach.
- Przykładowy kod GetAccountHierarchy pokazuje, jak pobrać listę wszystkich kont powiązanych z kontem menedżera Google Ads.
- Przykładowy kod ListAccessibleCustomers pokazuje
jak pobrać listę wszystkich kont, do których użytkownik ma bezpośredni dostęp.
Te konta mogą być używane jako prawidłowe wartości ustawienia
LoginCustomerId.
Domyślne dane uwierzytelniające aplikacji
Biblioteka klienta Ruby obsługuje też uwierzytelnianie za pomocą domyślnych danych uwierzytelniających aplikacji (ADC). Umożliwia ustawienie domyślnych danych uwierzytelniających aplikacji bez konieczności konfigurowania informacji OAuth 2.0 w konfiguracji aplikacji.
Jest to szczególnie przydatne w przypadku lokalnego programowania lub programowania w różnych interfejsach API Google, ponieważ możesz ponownie użyć tych samych danych uwierzytelniających, o ile mają one dostęp do odpowiednich zakresów OAuth 2.0.
W przypadku interfejsu Google Ads API upewnij się, że domyślne dane uwierzytelniające aplikacji mają dostęp do zakresu OAuth 2.0 https://www.googleapis.com/auth/adwords.
Aby używać domyślnych danych uwierzytelniających aplikacji, zalecamy używanie narzędzia wiersza poleceń Google Cloud i uwierzytelnianie w ADC:
gcloud auth application-default login
To polecenie otworzy przeglądarkę internetową, aby dokończyć proces uwierzytelniania na koncie Google. Po autoryzacji dane uwierzytelniające są przechowywane w standardowej lokalizacji. Następnie musisz zaktualizować aplikację, aby używała ADC.
Zalecamy używanie pliku konfiguracyjnego. Skopiuj plik google_ads_config.rb
do katalogu domowego, a następnie dodaj token programisty i ustaw wartość
use_application_default_credentials na true:
# The developer token is required to authenticate that you are allowed to
# make API calls.
c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
# 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ć zmienne GOOGLE_ADS_DEVELOPER_TOKEN i GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:
export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"
Możesz też przekazać te informacje programowo w czasie działania. Podczas inicjowania klienta w kodzie Ruby nie podawaj jawnych danych uwierzytelniających OAuth2. Biblioteka automatycznie wykryje i użyje danych uwierzytelniających skonfigurowanych za pomocą narzędzia wiersza poleceń Google Cloud. Nadal musisz określić token programisty.
# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
# Developer Token is mandatory for the Google Ads API.
config.developer_token = "YOUR_DEVELOPER_TOKEN"
# 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 oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end
Więcej informacji o dostępnych opcjach konfigurowania biblioteki klienta Ruby znajdziesz na stronie konfiguracji.