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 w .NET 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 aplikacja nie wymaga 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.

Skonfiguruj bibliotekę w ten sposób:

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

Więcej informacji znajdziesz w przewodniku po przepływie pracy konta 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:

  1. 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.
  2. Użytkownik uruchamia narzędzie wiersza poleceń, np. gcloud lub GenerateUserCredentialsprzykład kodu, aby autoryzować aplikację do zarządzania w jego imieniu wszystkimi kontami Google Ads.

Zainicjuj bibliotekę, używając danych logowania OAuth 2.0 użytkownika w ten sposób:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

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 i zarządza dynamicznie danymi logowania użytkownika OAuth 2.0 w każdej sesji użytkownika lub w każdym żądaniu, a następnie inicjuje obiekt GoogleAdsClient za pomocą tokena odświeżania aktywnego użytkownika:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = userSession.LoginCustomerId,
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = userSession.RefreshToken
};

GoogleAdsClient client = new GoogleAdsClient(config);

Od Google.Ads.GoogleAds v27.0.0 możesz też wstrzyknąć wstępnie skonfigurowany obiekt ICredential lub GoogleCredential bezpośrednio na stronie GoogleAdsConfig za pomocą właściwości Credentials.

Więcej informacji znajdziesz w przewodniku po przepływie pracy uwierzytelniania wielu użytkowników. Biblioteka klienta .NET zawiera 2 przykłady kodu do celów referencyjnych:

  1. Przykład kodu AuthenticateInAspNetCoreApplication pokazuje, jak utworzyć aplikację internetową, która w czasie działania uzyskuje uwierzytelnianie użytkownika, aby zarządzać jego kontami Google Ads w jego imieniu. Aplikacja używa danych logowania OAuth 2.0 użytkownika, aby pobrać kampanie z jego konta Google Ads.
  2. Przykładowy kod wiersza poleceń GenerateUserCredentials pokazuje, jak uzyskać uwierzytelnianie użytkownika w czasie działania programu, aby zarządzać jego kontami Google Ads w jego imieniu. Możesz użyć tego przykładu kodu jako odniesienia do tworzenia aplikacji na komputery, które wymagają uwierzytelnienia użytkownika.

Co zrobić, jeśli użytkownik zarządza 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 .NET zawiera te przykłady kodu, które pokazują, jak sobie radzić w takich sytuacjach:

  1. W GetAccountHierarchy przykładzie kodu pokazujemy, jak pobrać listę wszystkich kont na koncie menedżera Google Ads.
  2. W ListAccessibleCustomers przykładzie kodu pokazujemy, 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 ustawienia LoginCustomerId.

Domyślne uwierzytelnianie aplikacji

Biblioteka klienta .NET (v24.1.0 i nowsze wersje) obsługuje też uwierzytelnianie za pomocą domyślnego uwierzytelniania 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 uwierzytelnianie aplikacji ma dostęp do https://www.googleapis.com/auth/adwordszakresu protokołu OAuth 2.0.

Aby używać domyślnego uwierzytelniania aplikacji, ustaw opcję UseApplicationDefaultCredentials na true w pliku GoogleAdsConfig (lub ustaw zmienną środowiskową USE_APPLICATION_DEFAULT_CREDENTIALS=true podczas wczytywania konfiguracji za pomocą config.LoadFromEnvironmentVariables()):

GoogleAdsConfig config = new GoogleAdsConfig()
{
    UseApplicationDefaultCredentials = true,
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

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