استفاده پیشرفته

این راهنما نحوه سفارشی‌سازی چندین جنبه پیشرفته‌تر کتابخانه کارخواه Java را شرح می‌دهد. یک الگوی رایج این است که بسیاری از این ویژگی‌ها به‌جای روش‌های راحتی استاندارد، به Callable زیربنایی متکی هستند. The callable is generally a good place to look for other per-RPC features that aren't documented here.

درنگ

کتابخانه 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.
  }
}

می‌توانید زمان اتمام را روی ۲ ساعت یا بیشتر تنظیم کنید، اما ممکن است API همچنان برای درخواست‌های بسیار طولانی زمان اتمام درنظر بگیرد و خطای 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() (یا دسترسی‌دهنده خاص نسخه مانند getVersion26()) اتصال اساسی جدید و منابع مرتبط ایجاد می‌کند.

مطمئن شوید که وقتی دیگر به سرویس مشتری نیاز ندارید، آن را ببندید. می‌توانید این کار را در بلوک try-with-resources یا با فراخوانی close() در کلاینت سرویس انجام دهید.

اگر تلاش کنید از کارخواه سرویس بسته‌شده برای درخواست‌های API استفاده کنید، روش کارخواه سرویس java.util.concurrent.RejectedExecutionException را برمی‌گرداند.

اگر JAR بیشتر از ۳۲ مگابایت باشد، App Engine مستقر نمی‌شود

App Engine برای هر فایل بارگذاری‌شده سهمیه ۳۲ مگابایتی دارد. JAR برای google-ads به‌طور قابل‌توجهی بزرگ‌تر از این است، به‌ویژه هنگام استفاده از استقرارهای JAR سایه یا سایه‌دار. اگر JARها را به‌صورت دستی مستقر کنید، ممکن است خطاهایی مانند موارد زیر دریافت کنید:

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

درعوض، بااستفاده از افزایه Gradle یا افزایه Maven در App Engine مستقر کنید. هر افزونه گزینه enableJarSplitting را ارائه می‌دهد که هر JAR را به بخش‌های ۱۰ مگابایتی تقسیم می‌کند و آن‌ها را بارگذاری می‌کند.

وابستگی‌های سایه

اگر پروژه شما وابستگی‌هایی دارد که با وابستگی‌های کتابخانه تداخل دارد، سلسله‌مراتب وابستگی پروژه‌تان را بااستفاده از یکی از فرمان‌های زیر بررسی کنید، و سپس وابستگی‌های پروژه‌تان را درصورت نیاز اصلاح کنید (یا از صورت مواد استفاده کنید):

Maven

mvn dependency:tree

Gradle

./gradlew dependencies

اگر حل کردن تداخل‌های وابستگی امکان‌پذیر نیست، می‌توانید به‌جای آن به نسخه سایه‌دار کتابخانه وابسته باشید:

Maven

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

Gradle

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