Java

Google 提供了一个用于与 Ad Manager API 互动的 Java 客户端库。我们建议将客户端库与 Apache Maven 或 Gradle 搭配使用。

首先，在您选择的 IDE 中创建一个新项目，或将依赖项添加到现有项目中。Google 会将客户端库制品发布到 Maven 中央代码库，作为 com.google.api-ads/ad-manager。

Maven 

<!-- pom.xml -->
<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>ad-manager</artifactId>
  <version>0.56.0</version>
</dependency>

Gradle 

implementation 'com.google.api-ads:ad-manager:0.56.0'

配置凭据

Java 客户端库使用 OAuth2 和应用默认凭证 (ADC) 进行身份验证。

ADC 会按顺序在以下位置搜索凭据：

  1. GOOGLE_APPLICATION_CREDENTIALS 环境变量。
  2. 通过 Google Cloud CLI (gcloud CLI) 设置的用户凭据。
  3. 在 Google Cloud 上运行时，附加到 Google Cloud 资源的服务账号。

如需创建和配置 ADC 凭据，请参阅身份验证。

提交第一个请求

每项服务都有一个 ServiceClient 对象，其中包含每个 REST 方法的同步和异步方法。以下示例以同步方式读取 Network。

import com.google.ads.admanager.v1.GetNetworkRequest;
import com.google.ads.admanager.v1.Network;
import com.google.ads.admanager.v1.NetworkName;
import com.google.ads.admanager.v1.NetworkServiceClient;

public class SyncGetNetwork {

  public static void main(String[] args) throws Exception {
    syncGetNetwork();
  }

  public static void syncGetNetwork() throws Exception {
    try (NetworkServiceClient networkServiceClient = NetworkServiceClient.create()) {
      GetNetworkRequest request =
          GetNetworkRequest.newBuilder()
              .setName(NetworkName.of("[NETWORK_CODE]").toString())
              .build();
      Network response = networkServiceClient.getNetwork(request);
    }
  }
}

如需查看其他方法和资源的示例，请参阅 GitHub 代码库 googleapis/google-cloud-java。

记录 HTTP 请求和响应

com.google.api.client.http.HttpTransport 类用于发出所有 HTTP 请求。 此类使用 java.util.logging (JUL) 记录 HTTP 请求和响应的详细信息，包括网址、标头和内容。

如需启用日志记录，请将此类的记录器设置为 CONFIG 或更高级别的日志级别。具体步骤因您使用的日志记录实现而异。

7 月

如需启用日志记录，请在 logging.properties 文件中将 com.google.api.client.http.level 设置为 CONFIG 或更高级别。

handlers=java.util.logging.ConsoleHandler
com.google.api.client.http.level=CONFIG
java.util.logging.ConsoleHandler.level=CONFIG

或者，您也可以在 Java 代码中启用日志记录。


import com.google.api.client.http.HttpTransport;
import java.util.logging.ConsoleHandler;
import java.util.logging.Level;
import java.util.logging.Logger;

public static void enableLogging() {
  Logger logger = Logger.getLogger(HttpTransport.class.getName());
  logger.setLevel(Level.CONFIG);
  ConsoleHandler handler = new ConsoleHandler();
  handler.setLevel(Level.CONFIG);
  logger.addHandler(handler);
}

Log4j

如果您使用 Log4j 进行日志记录，则可以使用 Log4j JDK Logging Adapter 记录 JUL 消息。可以通过 SystemProperty 或使用 Log4jBridgeHandler 和 JUL logging.properties 文件来配置此设置。

系统属性

-Djava.util.logging.manager=org.apache.logging.log4j.jul.LogManager

Log4j Bridge 处理程序

handlers = org.apache.logging.log4j.jul.Log4jBridgeHandler
org.apache.logging.log4j.jul.Log4jBridgeHandler.propagateLevels = true

这些设置会将 Ad Manager API 日志写入任何级别为 CONFIG 或更高级别的 Logger。以下示例 log4j2.xml 文件配置了一个写入 System.out 的 Logger。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout pattern="%m%n"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="com.google.api.client.http.HttpTransport" level="debug">
      <AppenderRef ref="Console"/>
    </Logger>
    <Root level="error">
      <AppenderRef ref="Console"/>
    </Root>
  </Loggers>
</Configuration>

处理错误

Java 客户端库中的所有 Ad Manager API 错误都是 ApiException 的子类。

ApiException.getReason() 方法会返回一个唯一标识错误类型的字符串。使用此属性可确定如何处理错误。

除 404 Not Found 和 401 Unauthorized 之外的所有错误都包含 ErrorDetails 以及其他信息。对于 400 Bad Request 错误，ErrorDetails 包含一个 BadRequest 对象，其中包含 FieldViolations 的列表。

try {
  // ...
} catch (ApiException apiException) {
  // HTTP status code enum
  com.google.api.gax.rpc.StatusCode statusCode = apiException.getStatusCode();

  // Unique identifier for the type of error
  String errorCode = apiException.getReason();

  // Human readable error message
  String errorMessage = apiException.getMessage();

  // Additional information is available in ErrorDetails.
  ErrorDetails errorDetails = apiException.getErrorDetails();
  if (errorDetails != null) {
    // Additional information for 400 Bad Request errors
    if (errorDetails.getBadRequest() != null) {
      // List of field violations
      List<BadRequest.FieldViolation> fieldViolations =
          errorDetails.getBadRequest().getFieldViolationsList();
    }
  }
}

Ad Manager API 错误还包含一个唯一的 request_id，您可以将其提供给支持团队，以便获得问题排查方面的帮助。以下示例提取了 request_id。

ErrorDetails errorDetails = apiException.getErrorDetails();
if (errorDetails != null && errorDetails.getRequestInfo() != null) {
  // Unique request identifier.
  String requestId = errorDetails.getRequestInfo().getRequestId();
}

构建资源名称

客户端库提供了用于根据 ID 构建资源名称的辅助类。

import com.google.ads.admanager.v1.OrderName;

// ...

//  Constructs a String in the format:
//  "networks/{networkCode}/orders/{orderId}"
OrderName.of("123", "789");

配置代理设置

Java 客户端库同时支持 http.proxyHost 和 https.proxyHost 系统属性设置。如需详细了解这些设置，请参阅 Java 网络和代理。