Java

‫Google מספקת ספריית לקוח של Java לאינטראקציה עם Ad Manager API. מומלץ להשתמש בספריית הלקוח עם Apache Maven או Gradle.

כדי להתחיל, יוצרים פרויקט חדש ב-IDE שבחרתם או מוסיפים את התלות לפרויקט קיים. ‫Google מפרסמת פריטי מידע שנוצרו בתהליך הפיתוח (artifacts) של ספריית הלקוח במאגר המרכזי של 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 (ה-CLI של gcloud).
  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, כותרות ותוכן.

כדי להפעיל את הרישום ביומן, צריך להגדיר את ה-logger של המחלקה הזו לרמת יומן של 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 וקובץ JUL logging.properties.

מאפיין מערכת

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

Log4j Bridge Handler

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

ההגדרות האלה כותבות את יומני ה-API של Ad Manager לכל Logger ברמה 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");

קביעת הגדרות לשרת proxy

ספריית הלקוח של Java מכבדת את הגדרות המאפיינים של המערכת http.proxyHost ו-https.proxyHost. לפרטים נוספים על ההגדרות האלה, קראו את המאמר Java networking and Proxies.