驗證及授權

與其他 Google API 相同，Google Ads API 也使用 OAuth 2.0 通訊協定進行驗證及授權。OAuth 2.0 可讓 Google Ads API .NET 用戶端應用程式存取使用者的 Google Ads 帳戶，不必處理或儲存使用者的登入資訊。

瞭解 Google Ads 存取模式

如要有效使用 Google Ads API，請先瞭解 Google Ads 存取模式的運作方式。請參閱 Google Ads 存取權模式指南。

OAuth 工作流程

使用 Google Ads API 時，通常會用到三種工作流程。

服務帳戶流程

如果應用程式不需要任何人為互動，建議採用這個工作流程。這項工作流程需要設定步驟，使用者必須將服務帳戶新增至 Google Ads 帳戶。應用程式隨後就能使用服務帳戶的憑證，管理使用者的 Google Ads 帳戶。

請按照下列方式設定程式庫：

// 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);

如要瞭解詳情，請參閱服務帳戶工作流程指南。

單一使用者驗證流程

如果無法使用服務帳戶，可以採用這個工作流程。這項工作流程需要完成兩個設定步驟：

  1. 使用 Google Ads API 授權單一使用者存取所有要管理的帳戶。常見做法是授予使用者 Google Ads API 管理員帳戶的存取權，並連結該管理員帳戶下的所有 Google Ads 帳戶。
  2. 使用者執行 gcloud 等指令列工具或GenerateUserCredentials程式碼範例，授權應用程式代表他們管理所有 Google Ads 帳戶。

使用使用者的 OAuth 2.0 憑證初始化程式庫，如下所示：

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);

詳情請參閱單一使用者驗證工作流程指南。

多使用者驗證流程

如果您的應用程式允許使用者登入，並授權應用程式代表他們管理 Google Ads 帳戶，建議採用這個工作流程。應用程式會根據每個使用者工作階段或要求，動態建構及管理 OAuth 2.0 使用者憑證，然後使用有效使用者的更新權杖初始化 GoogleAdsClient：

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);

自 Google.Ads.GoogleAds v27.0.0 起，您也可以使用 Credentials 屬性，直接在 GoogleAdsConfig 上插入預先設定的 ICredential 或 GoogleCredential 物件。

詳情請參閱多使用者驗證工作流程指南。.NET 用戶端程式庫包含兩個程式碼範例供您參考：

  1. AuthenticateInAspNetCoreApplication 程式碼範例說明如何建構網頁應用程式，在執行階段取得使用者驗證，代表使用者管理 Google Ads 帳戶。應用程式會使用使用者的 OAuth 2.0 憑證，擷取 Google Ads 帳戶中的廣告活動。
  2. GenerateUserCredentials 命令列程式碼範例說明如何在執行階段取得使用者驗證，代表使用者管理 Google Ads 帳戶。您可以參考這個程式碼範例，建構需要使用者驗證的電腦應用程式。

如果使用者管理多個帳戶，該怎麼辦？

使用者通常會管理多個 Google Ads 帳戶，可能是直接存取帳戶，也可能是透過 Google Ads 管理員帳戶。.NET 用戶端程式庫提供下列程式碼範例，說明如何處理這類情況：

  1. GetAccountHierarchy 程式碼範例說明如何擷取 Google Ads 管理員帳戶下的所有帳戶清單。
  2. ListAccessibleCustomers 程式碼範例說明如何擷取使用者可直接存取的所有帳戶清單。這些帳戶隨後可用於 LoginCustomerId 設定的有效值。

應用程式預設憑證

.NET 用戶端程式庫 (v24.1.0 以上版本) 也支援使用應用程式預設憑證進行驗證。

如果您要進行本機開發，或是針對不同的 Google API 進行開發，這項功能就特別實用，因為只要憑證可以存取必要的 OAuth 2.0 範圍，您就能重複使用相同的憑證。

如果是 Google Ads API，請確認應用程式預設憑證可以存取 https://www.googleapis.com/auth/adwords OAuth 2.0 範圍。

如要使用應用程式預設憑證，請在 GoogleAdsConfig 中將 UseApplicationDefaultCredentials 選項設為 true (或在透過 config.LoadFromEnvironmentVariables() 載入設定時，設定 USE_APPLICATION_DEFAULT_CREDENTIALS=true 環境變數)：

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

如要進一步瞭解設定 .NET 用戶端程式庫的可用選項，請參閱設定頁面。