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

این راهنما نحوه سفارشی‌سازی کردن چندین جنبه پیشرفته‌تر از کتابخانه کارخواه Java را شرح می‌دهد. یک الگوی رایج این است که بسیاری از این ویژگی‌ها به‌جای روش‌های راحتی استاندارد، به Callable زیربنایی متکی هستند. قابل‌فراخوانی معمولاً مکان خوبی برای جستجوی سایر ویژگی‌های per-RPC است که در اینجا مستند نشده‌اند.

درنگ

کتابخانه 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 > 32 MB باشد، App Engine نمی‌تواند مستقر شود

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

ERROR: (gcloud.app.deploy) Cannot upload file [<your-app>/WEB-INF/lib/google-ads-48.0.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.0.0</version>
</dependency>

Gradle

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