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

يوضح هذا الدليل كيفية تخصيص العديد من الجوانب الأكثر تقدمًا لمكتبة برامج 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 جديد.

يجب التأكُّد من إغلاق العميل عندما لا يكون مطلوبًا. ويمكن إجراء ذلك من خلال حظر تجربة الموارد أو من خلال طلب 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 ميغابايت ويحمّل بدلاً من ذلك.

تبعيات الظل

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

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

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

Maven

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

Gradle

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