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

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

تایم اوت

کتابخانه جاوا سطحی را برای تنظیم زمان‌های انتظار در سطح هر فراخوانی فراهم می‌کند. مقدار پیش‌فرض بر اساس تنظیم method_config/timeout در googleads_grpc_service_config.json تنظیم می‌شود. اگر نیاز به اعمال محدودیت کوتاه‌تری در حداکثر زمان برای یک فراخوانی API دارید، مقدار کمتری را تنظیم کنید.

برای استفاده از این ویژگی، شیء 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 را برگرداند. اگر این مشکل ایجاد شود، معمولاً بهتر است کوئری را تقسیم کرده و تکه‌ها را به صورت موازی اجرا کنید. این کار از وضعیتی که یک درخواست طولانی با شکست مواجه می‌شود و تنها راه بازیابی، شروع مجدد درخواست از ابتدا است، جلوگیری می‌کند.

تنظیمات را دوباره امتحان کنید

کتابخانه جاوا همچنین سطحی را برای پیکربندی تنظیمات تلاش مجدد در سطح هر فراخوانی فراهم می‌کند. برای استفاده از این ویژگی، شیء 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() ) است که کلاس‌های سرویس API را به طور همزمان بارگذاری می‌کند تا مکانیزم مناسبی برای ساخت کلاینت‌های سرویس فراهم کند.

اگر عملکرد اولین درخواست در مسیر بحرانی برنامه شما قرار دارد، این مراحل را دنبال کنید:

  1. قبل از ارائه درخواست‌های کاربر، GoogleAdsClient را در هنگام راه‌اندازی ایجاد کنید.

  2. وقتی فرآیند برای اولین بار شروع می‌شود، چند درخواست گرم کردن به 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.
    }
  }
}

درخواست‌های گرم کردن (warm-up) فقط باید یک بار در هر فرآیند اجرا شوند. هر بار ایجاد کلاینت سرویس بعدی، به طور خودکار از کلاس‌های از پیش بارگذاری شده استفاده مجدد می‌کند.

استفاده مجدد از سرویس گیرنده

شما باید در صورت امکان از نمونه‌های کلاینت سرویس دوباره استفاده کنید، زیرا هر فراخوانی GoogleAdsClient.getLatestVersion().createYYYServiceClient() (یا یک accessor مخصوص نسخه مانند getVersion25() ) یک اتصال زیربنایی جدید و منابع مرتبط ایجاد می‌کند.

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

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

اگر فایل JAR بزرگتر از ۳۲ مگابایت باشد، App Engine اجرا نمی‌شود.

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

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

در عوض، با استفاده از افزونه App Engine Gradle یا افزونه Maven ، آن را مستقر کنید. هر افزونه یک گزینه enableJarSplitting ارائه می‌دهد که هر JAR را به قطعات 10 مگابایتی تقسیم کرده و آنها را آپلود می‌کند.

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

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

ماون 

mvn dependency:tree

گرادل 

./gradlew dependencies

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

ماون 

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

گرادل 

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