Java

Google 提供 Java 用戶端程式庫，可用於與 Ad Manager API 互動。建議您搭配 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.59.0</version>
</dependency>

Gradle 

implementation 'com.google.api-ads:ad-manager:0.59.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 以上的記錄器。以下 log4j2.xml 檔案範例會設定寫入 System.out 的記錄器。

<?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>

處理錯誤

所有 Ad Manager API 錯誤都是 Java 用戶端程式庫中 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");

指定 Proxy 設定

Java 用戶端程式庫會遵循 http.proxyHost 和 https.proxyHost 系統屬性設定。如要進一步瞭解這些設定，請參閱「Java 網路和 Proxy」。