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

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

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

توفّر مكتبة 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.

يتعذّر نشر 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-38.0.0.jar],
which has size [66095767] (greater than maximum allowed size of [33554432])

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

المهام التابعة غير المباشرة

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

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

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

Maven

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

Gradle

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