الاستخدام المتقدّم

يوضّح هذا الدليل كيفية تخصيص العديد من الجوانب الأكثر تقدّمًا في مكتبة برامج Java. ويتمثل النمط الشائع في أنّ العديد من هذه الميزات تعتمد على Callable الأساسي بدلاً من طرق التسهيل العادية. The callable is generally a good place to look for other per-RPC features that aren't documented here.

عملية استبعاد للقناة لمهلة معيّنة

توفّر مكتبة Java واجهة لضبط مهلات على مستوى كل طلب. يتم ضبط القيمة التلقائية استنادًا إلى الإعداد method_config/timeout في googleads_grpc_service_config.json. اضبط قيمة أقل إذا كنت بحاجة إلى فرض حدّ زمني أقصر على الحد الأقصى لمدة طلب البيانات من واجهة برمجة التطبيقات.

لاستخدام هذه الميزة، استدعِ عنصر Callable مباشرةً. على سبيل المثال، عند استدعاء GoogleAdsService.searchStream()، اضبط المهلة على النحو التالي:

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  // Constructs the SearchGoogleAdsStreamRequest.
  SearchGoogleAdsStreamRequest request =
      SearchGoogleAdsStreamRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setQuery("SELECT campaign.id, campaign.name FROM campaign")
          .build();

  // Executes the API call with a timeout of 5 minutes.
  ServerStream<SearchGoogleAdsStreamResponse> stream =
      googleAdsServiceClient
          .searchStreamCallable()
          .call(
              request,
              GrpcCallContext.createDefault()
                  .withTimeout(Duration.of(5, ChronoUnit.MINUTES)));
  for (SearchGoogleAdsStreamResponse response : stream) {
    // Processes the response rows.
  }
}

يمكنك ضبط المهلة على ساعتين أو أكثر، ولكن قد تستمر واجهة برمجة التطبيقات في إنهاء مهلة الطلبات التي تستغرق وقتًا طويلاً جدًا وتعرض الخطأ DEADLINE_EXCEEDED. إذا أصبحت هذه مشكلة، من الأفضل عادةً تقسيم طلب البحث وتنفيذ الأجزاء بالتوازي، فهذا يتجنّب الموقف الذي يفشل فيه طلب طويل الأمد والطريقة الوحيدة للاسترداد هي تشغيل الطلب مرة أخرى من البداية.

إعادة محاولة الإعدادات

توفّر مكتبة Java أيضًا مساحة لضبط إعدادات إعادة المحاولة على مستوى كل عملية استدعاء. لاستخدام هذه الميزة، يمكنك استدعاء العنصر Callable مباشرةً. على سبيل المثال، عند الاتصال بـ GoogleAdsService.searchStream()، اضبط إعدادات إعادة المحاولة على النحو التالي:

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  SearchGoogleAdsStreamRequest request =
      SearchGoogleAdsStreamRequest.newBuilder()
          .setCustomerId(Long.toString(customerId))
          .setQuery("SELECT campaign.id, campaign.name FROM campaign")
          .build();

  // Creates a context object with the custom retry settings.
  GrpcCallContext context =
      GrpcCallContext.createDefault()
          .withRetrySettings(
              RetrySettings.newBuilder()
                  .setInitialRetryDelay(Duration.ofMillis(10L))
                  .setMaxRetryDelay(Duration.ofSeconds(10L))
                  .setRetryDelayMultiplier(1.4)
                  .setMaxAttempts(10)
                  .setLogicalTimeout(Duration.ofSeconds(30L))
                  .build());

  // Issues the streaming search request.
  ServerStream<SearchGoogleAdsStreamResponse> stream =
      googleAdsServiceClient.searchStreamCallable().call(request, context);
  for (SearchGoogleAdsStreamResponse response : stream) {
    // Processes the response rows.
  }
}

تحسين أداء وقت بدء التشغيل

قد تلاحظ تأخيرًا بسيطًا في المرة الأولى التي يتم فيها إنشاء مثيل GoogleAdsClient. ويرجع ذلك إلى الواجهة السلسة للخدمات (GoogleAdsClient.getLatestVersion())، والتي تحمّل فئات خدمة واجهة برمجة التطبيقات في وقت واحد لتوفير آلية ملائمة لإنشاء عملاء الخدمة.

إذا كان أداء الطلب الأول يقع ضمن المسار الحرج لتطبيقك، فاتّبِع الخطوات التالية:

1. أنشئ GoogleAdsClient عند بدء التشغيل، قبل عرض طلبات المستخدمين.

2. أرسِل بعض طلبات الإحماء إلى Google Ads API عند بدء العملية لأول مرة. على سبيل المثال:

   // Runs some warm-up requests.
   try (GoogleAdsServiceClient googleAdsServiceClient =
       googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
     // Runs 5 warm-up requests. In our profiling we see that 90% of
     // performance loss is only experienced on the first API call. After 3
     // subsequent calls we saw a negligible improvement in performance.
     for (int i = 0; i < 5; ++i) {
       // Warm-up queries are run with a nonexistent CID so the calls will
       // fail. If you have a CID that you know will be accessible with the
       // OAuth credentials provided you may want to provide that instead and
       // avoid the try-catch.
       try {
         googleAdsServiceClient.search("-1", "Warm-up query");
       } catch (ApiException ex) {
         // Do nothing, we're expecting this to fail.
       }
     }
   }
   

يجب تنفيذ طلبات الإحماء مرة واحدة فقط لكل عملية. ويؤدي كل إنشاء لاحق لعميل الخدمة إلى إعادة استخدام الفئات المحمَّلة مسبقًا تلقائيًا.

إعادة استخدام عميل الخدمة

يجب إعادة استخدام مثيلات برامج خدمة العملاء حيثما أمكن ذلك، لأنّ كل طلب إلى GoogleAdsClient.getLatestVersion().createYYYServiceClient() (أو دالة استرداد قيمة خاصة بإصدار معيّن، مثل getVersion26()) يؤدي إلى إنشاء اتصال أساسي جديد وموارد مرتبطة به.

تأكَّد من إغلاق عميل الخدمة عندما لا تعود هناك حاجة إليه. يمكنك إجراء ذلك في مجموعة try-with-resources أو من خلال استدعاء close() في عميل الخدمة.

إذا حاولت استخدام عميل خدمة مغلق لطلب بيانات من واجهة برمجة التطبيقات، ستعرض طريقة عميل الخدمة الخطأ java.util.concurrent.RejectedExecutionException.

يتعذّر نشر App Engine إذا كان حجم ملف JAR أكبر من 32 ميغابايت

يبلغ الحدّ الأقصى المسموح به في App Engine‏ 32 ميغابايت لكل ملف يتم تحميله. إنّ ملف JAR لـ google-ads أكبر بكثير من هذا، خاصةً عند استخدام عمليات نشر ملفات JAR المظللة أو المظللة. إذا نشرت ملفات JAR يدويًا، قد تظهر لك أخطاء مثل:

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-48.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

بدلاً من ذلك، يمكنك النشر باستخدام المكوّن الإضافي Gradle أو المكوّن الإضافي Maven في App Engine. يوفّر كل مكوّن إضافي enableJarSplittingخيارًا يقسّم كل ملف JAR إلى أجزاء بحجم 10 ميغابايت ويحمّل هذه الأجزاء بدلاً من الملف.

المهام التابعة الظلية

إذا كان مشروعك يتضمّن عناصر تابعة تتعارض مع العناصر التابعة للمكتبة، يمكنك فحص التسلسل الهرمي للعناصر التابعة في مشروعك باستخدام أحد الأوامر التالية، ثم تعديل العناصر التابعة في مشروعك حسب الحاجة (أو استخدام قائمة المواد):

mvn dependency:tree

./gradlew dependencies

إذا كان حلّ التعارضات في التبعيات غير ممكن، يمكنك الاعتماد على الإصدار المظلَّل من المكتبة بدلاً من ذلك:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads-shadowjar</artifactId>
  <version>48.0.0</version>
</dependency>

implementation 'com.google.api-ads:google-ads-shadowjar:48.0.0'