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

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

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

توفّر مكتبة 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() (أو دالة استرداد قيمة خاصة بإصدار معيّن، مثل getVersion25()) يؤدي إلى إنشاء اتصال أساسي جديد وموارد مرتبطة به.

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

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

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

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

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-46.1.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>46.1.0</version>
</dependency>

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