Java

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

כדי להתחיל, יוצרים פרויקט חדש בסביבת הפיתוח המשולבת (IDE) שבחרתם או מוסיפים את התלות לפרויקט קיים. ‫Google מפרסמת ארטיפקטים של ספריות לקוח במאגר Maven Central בתור com.google.api-ads/ad-manager.

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

implementation 'com.google.api-ads:ad-manager:0.1.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 או גבוהה יותר. השלבים משתנים בהתאם להטמעת הרישום ביומן שבה אתם משתמשים.

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.

כל השגיאות מלבד 404 Not Found ו-401 Unauthorized מכילות את ErrorDetails עם מידע נוסף.

שגיאות בניתוח

השדה 'סיבת השגיאה' מזהה באופן ייחודי את סוגי השגיאות. בשדה הזה מציינים איך לטפל בשגיאה.

ErrorDetails errorDetails = apiException.getErrorDetails();
if (errorDetails != null) {
  // Unique error code in UPPER_SNAKE_CASE.
  String errorCode = errorDetails.getReason();
}

שגיאות ב-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.