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

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

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

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

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

try (GoogleAdsServiceClient googleAdsServiceClient =
    googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
  // Constructs the SearchGoogleAdsStreamRequest.
  SearchGoogleAdsStreamRequest request = ...

  // Executes the API call, with a timeout of 5 minutes.
  ServerStream<SearchGoogleAdsStreamResponse> result = googleAdsServiceClient
      .searchStreamCallable()
      .call(request,
          GrpcCallContext.createDefault().withTimeout(Duration.of(5, ChronoUnit.MINUTES)));
}

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

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

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

// 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());

// Creates and issues a search Google Ads stream request.
ServerStream<SearchGoogleAdsStreamResponse> stream =
    googleAdsServiceClient.searchStreamCallable().call(request, context);

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

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

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

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 (GoogleAdsException ex) {
         // Do nothing, we're expecting this to fail.
       }
     }
   }
   

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

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

يجب إعادة استخدام نُسخ عميل الخدمة كلما أمكن ذلك، لأنّ كلّ طلب إلى GoogleAdsClient.getVersionXXX().createYYYServiceClient() سيؤدّي إلى إنشاء اتصال TCP جديد.

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

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

يتعذّر على "محرّك التطبيقات" نشر حزمة JAR إذا كانت أكبر من 32 ميغابايت.

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

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

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

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

إذا كان مشروعك يتضمّن تبعيات تتعارض مع تبعيات المكتبة، عليك فحص تبعيات مشروعك باستخدام أحد الأوامر التالية، ثم تعديل تبعيات مشروعك حسب الحاجة.

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

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

Maven

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

Gradle

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