Java

توفّر Google مكتبة برامج Java للتفاعل مع Ad Manager API. ننصحك باستخدام مكتبة العميل مع Apache Maven أو Gradle.

للبدء، أنشئ مشروعًا جديدًا في بيئة التطوير المتكاملة التي تختارها أو أضِف التبعية إلى مشروع حالي. تنشر Google عناصر مكتبة العميل في مستودع Maven المركزي على النحو التالي: com.google.api-ads/ad-manager.

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

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

ضبط بيانات الاعتماد

تستخدم مكتبة برامج Java بروتوكول OAuth2 وبيانات الاعتماد التلقائية للتطبيق (ADC) للمصادقة.

تبحث ADC عن بيانات الاعتماد بالترتيب في المواقع الجغرافية التالية:

1. متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS
2. بيانات اعتماد المستخدم التي تم إعدادها من خلال واجهة سطر الأوامر في Google Cloud ‏(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);
    }
  }
}
SyncGetNetwork.java

للاطّلاع على أمثلة على الطرق والموارد الأخرى، يُرجى الانتقال إلى مستودع GitHub googleapis/google-cloud-java.

تسجيل طلبات HTTP والردود عليها

تُجري فئة com.google.api.client.http.HttpTransport جميع طلبات HTTP. تستخدم هذه الفئة java.util.logging (JUL) لتسجيل تفاصيل طلبات واستجابات HTTP، بما في ذلك عنوان URL والعناوين والمحتوى.

لتفعيل التسجيل، اضبط المسجِّل لهذه الفئة على مستوى تسجيل CONFIG أو أعلى. تختلف خطوات ذلك حسب تنفيذ التسجيل الذي تستخدمه.

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

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);
}

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

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

<?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 والخوادم الوكيلة.