通过 Bing Ads API 开始使用 Java

项目
11/13/2024

重要

建议使用 Java 11 或更高版本。我们支持的最低 Java 版本为 1.8。使用 1.8 时，需要从依赖项中排除 CXF。可以使用 Maven 生成此示例文件。

若要开始使用 Java 开发 Bing Ads API 应用程序，可以从提供的示例开始，或者按照 Web 或桌面应用程序的应用程序演练之一进行操作。

你将需要具有在生产或沙盒中访问Microsoft广告的用户凭据。对于生产环境，需要生产开发人员令牌。所有沙盒客户端都可以使用通用沙盒开发人员令牌，即 BBD37VB98。有关详细信息，请参阅 Bing Ads API 和沙盒入门。

若要通过 OAuth 进行身份验证，还必须注册应用程序并获取相应的客户端标识符。如果要开发 Web 应用程序，还需要记下客户端密码和重定向 URI。有关在生产环境中注册应用程序和授权代码授予流的详细信息，请参阅使用 OAuth 进行身份验证和使用 SDK 进行身份验证。尽管在生产环境中必须使用自己的应用程序 ID (即客户端 ID) ，但所有Microsoft广告客户都可以使用沙盒中的公共“教程示例应用”客户端 ID，即 00001111-aaaa-2222-bbbb-3333cccc4444。有关详细信息，请参阅沙盒。

安装 SDK

Java SDK Bing Ads取决于 Maven 存储库中列出的库。

创建 Maven 项目并包含 microsoft.bingads Maven 项目（如下所示）时，会自动安装其他依赖项。如果不使用 Maven 项目，则必须包含每个依赖项的正确版本。有关详细信息，请参阅演练：在 Java 中Bing Ads API Web 应用程序或演练：在 Java 中Bing Ads 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 或桌面应用程序的应用程序演练之一进行操作。

配置沙盒

若要使用沙盒环境，请在项目源根目录（例如 ProjectName\src\bingads.properties）中创建名为 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 客户端实现。你可能希望自定义 HTTP 客户端以配置某些功能，例如，如果使用不同的 JAX-RS 实现来更改 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.dumptrue：

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 服务地址
 处理服务错误和异常
 沙盒

通过