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 и Application Default Credentials (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-запросах и ответах, включая URL, заголовки и контент.

Чтобы включить ведение журнала, задайте для этого класса уровень ведения журнала CONFIG или выше. Порядок действий зависит от используемой реализации ведения журнала.

ИЮЛ

Чтобы включить ведение журнала, задайте для параметра com.google.api.client.http.level значение CONFIG или выше в файле logging.properties.

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 и файла logging.properties JUL.

Свойство системы

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

Обработчик моста Log4j

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 являются подклассами ApiException в клиентской библиотеке Java.

Метод 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();
}

Как создавать названия ресурсов

Клиентская библиотека предоставляет вспомогательные классы для создания названий ресурсов на основе идентификаторов.

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 networking and Proxies (Сети Java и прокси-серверы).