Java

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

כדי להתחיל, יוצרים פרויקט חדש בסביבת הפיתוח המשולבת (IDE) שבחרתם או מוסיפים את התלות לפרויקט קיים. ‫Google מפרסמת ארטיפקטים של ספריות לקוח במאגר Maven Central בתור 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 וב-Application Default Credentials‏ (ADC) לצורך אימות.

החיפוש של פרטי הכניסה ב-ADC מתבצע בסדר הבא:

1. משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.
2. פרטי כניסה של משתמשים שהוגדרו באמצעות ה-CLI של gcloud (ה-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);
    }
  }
}
SyncGetNetwork.java

דוגמאות לשיטות ולמשאבים אחרים זמינות במאגר 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 כדי לרשום הודעות 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

ההגדרות האלה כותבות יומנים של Ad Manager API לכל Logger ברמה של CONFIG ומעלה. בדוגמה הבאה, קובץ log4j2.xml מגדיר Logger שכותב ל-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.