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

يوضح هذا الدليل كيفية تخصيص العديد من الجوانب الأكثر تقدمًا لمكتبة برامج 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 أكبر بكثير من ذلك، حتى باستخدام عمليات نشر أوعية الظل/الظل. إذا كنت تنشر الأواني يدويًا، قد تظهر لك أخطاء، مثل:

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

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

تبعيات الظل

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

mvn dependency:tree

./gradlew dependencies

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

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

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