開始搭配使用Java與 Bing Ads API

發行項
10/24/2024

重要事項

建議您使用 Java 11 或更新版本。我們支援的最低 Java 版本為 1.8。使用 1.8 時，您必須從相依性排除 CXF。您可以使用 Maven 建置此範例檔案。

若要開始使用 Java 開發Bing Ads API 應用程式，您可以從提供的範例開始，或遵循 Web 或傳統型應用程式的其中一個應用程式逐步解說。

您需要可在生產或沙箱中存取 Microsoft Advertising 的用戶認證。針對生產環境，您需要生產開發人員令牌。所有沙盒用戶端都可以使用通用沙盒開發人員令牌，也就是 BBD37VB98。如需詳細資訊，請參閱開始使用Bing Ads API 和沙盒。

若要透過 OAuth 進行驗證，您也必須註冊應用程式並取得對應的用戶端識別碼。如果您要開發 Web 應用程式，也需要記下用戶端密碼和重新導向 URI。如需在生產環境中註冊應用程式和授權碼授與流程的詳細資訊，請參閱使用 OAuth 進行驗證和使用 SDK 進行驗證。雖然在生產環境中，您必須使用自己的應用程式標識碼 (也就是用戶端標識符) ，但所有Microsoft廣告客戶都可以在沙盒中使用公用的「教學課程範例應用程式」用戶端標識符，也就是 00001111-aaaa-2222-bbbb-3333cccc4444。如需詳細資訊，請參閱沙盒。

安裝 SDK

Bing Ads Java SDK 取決於 Maven 存放庫中列出的連結庫。

當您建立 Maven 專案並包含如下所示 的 microsoft.bingads Maven 成品時，會自動安裝其他相依性。如果您不是使用 Maven 專案，則必須包含每個相依性的正確版本。如需詳細資訊，請參閱逐步解說：Bing Ads Java 中的 API Web 應用程式或逐步解說：Bing Ads Java 應用程式中的 API 傳統型應用程式範例。

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <dependencies>
    <dependency>
      <groupId>com.microsoft.bingads</groupId>
      <artifactId>microsoft.bingads</artifactId>
      <version>13.0.10</version>
    </dependency>
  </dependencies>
</project>

注意事項

例如，包含 13.0.10 版。如需最新 SDK 相依性版本的詳細資訊，請參閱 Bing Ads Java SDK GitHub README.md。

逐步解說

安裝 Bing Ads Java SDK 之後，您可以瀏覽 Bing Ads API 程式代碼範例、從 GitHub 下載範例，或遵循 Web 或傳統型應用程式的其中一個應用程式逐步解說。

設定沙箱

若要使用沙盒環境，請在專案來源根目錄中建立名為 bingads.properties 的新文本檔，例如 ProjectName\src\bingads.properties ，並新增下列文字。以下是 bingads.properties 檔案的完整內容。如果沙箱環境設定格式不正確或遺失，則默認環境為生產環境。

environment=Sandbox

您也可以個別設定每個 ServiceClient 的環境，如下所示。

CustomerService = new ServiceClient<ICustomerManagementService>(
    authorizationData,
    ApiEnvironment.SANDBOX,
    ICustomerManagementService.class
);

無論您是全域或個別設定 ServiceClient 環境，您也必須將 OAuth 環境設定為沙箱。

final OAuthDesktopMobileAuthCodeGrant oAuthDesktopMobileAuthCodeGrant = new OAuthDesktopMobileAuthCodeGrant(
    ClientId, 
    ApiEnvironment.SANDBOX
);

具有客戶端密碼和自定義重新導向 URI 的 Web 應用程式應該使用 OAuthWebAuthCodeGrant，如下所示。

OAuthWebAuthCodeGrant oAuthWebAuthCodeGrant = new OAuthWebAuthCodeGrant(
    ClientId, 
    ClientSecret, 
    new URL(RedirectUri),
    ApiEnvironment.SANDBOX
);

在控制台中記錄要求和回應標頭。 TrackingId 包含在回應標頭中。

MessageHandler.getInstance().setTraceOn(true);

自訂 HTTP 用戶端

對於大部分的應用程式，我們建議在依賴 Apache CXF JAX-RS 用戶端的 Bing Ads Java SDK 中使用預設 HTTP 用戶端實作。如果您使用不同的 JAX-RS 實作、變更 HTTP 逾時、Proxy 組態或其他設定，您可以自訂 HTTP 用戶端來設定一些功能，例如啟用壓縮。

若要這樣做，您可以建立自訂 HttpClientProvider 物件，並在進行服務呼叫之前將它傳遞至 GlobalSettings.setHttpClientProvider() 。例如：

GlobalSettings.setHttpClientProvider(new HttpClientProvider() 
{ 
    @Override 
    protected ClientBuilder configureClientBuilder(ClientBuilder clientBuilder) { 
        return super.configureClientBuilder(clientBuilder) 
            // override default connect timeout 
            .connectTimeout(90, TimeUnit.SECONDS)
            // override default read timeout
            .readTimeout(5, TimeUnit.MINUTES) 
            // enable compression (if using Jersey client)
            .register(org.glassfish.jersey.message.GZipEncoder.class)
            .register(org.glassfish.jersey.client.filter.EncodingFilter.class);
    }
});

記錄服務呼叫

若要啟用要求和回應訊息的記錄，您可以將屬性設定 com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump 為 true：

System.setProperty("com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump", "true");

根據預設，Bing Ads Java SDK 會使用 Apache CXF 進行服務呼叫，這會依賴適用於 Java 的簡單記錄外觀來寫入其記錄。若要將記錄的訊息輸出到主控台，您可以將實 slf4j-simple 作新增至應用程式相依性。例如：

<dependency> 
    <groupId>org.slf4j</groupId> 
    <artifactId>slf4j-simple</artifactId> 
    <version>2.0.12</version> 
</dependency>

另請參閱

Bing Ads API 用戶端連結庫
 Bing Ads API 程式代碼範例
 Bing Ads API Web 服務位址
 處理服務錯誤和例外狀況
 沙箱

共用方式為