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

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

تایم اوت

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

برای استفاده از این ویژگی باید مستقیماً از شیء قابل فراخوانی استفاده کنید. به عنوان مثال، اگر با 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)));
}

می‌توانید زمان‌بندی را روی ۲ ساعت یا بیشتر تنظیم کنید، اما API ممکن است همچنان درخواست‌های طولانی‌مدت را به پایان برساند و خطای DEADLINE_EXCEEDED را برگرداند. اگر این مشکل به وجود آمد، معمولاً بهتر است پرس و جو را تقسیم کنید و تکه ها را به صورت موازی اجرا کنید. این از موقعیتی جلوگیری می کند که یک درخواست طولانی مدت با شکست مواجه شود و تنها راه بازیابی این است که درخواست را دوباره از ابتدا راه اندازی کنید.

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

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

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

  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() در سرویس گیرنده انجام داد.

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

اگر JAR > 32 مگابایت باشد، موتور برنامه اجرا نمی‌شود

App Engine برای هر فایل آپلود شده 32 مگابایت سهمیه دارد. JAR برای google-ads به طور قابل توجهی بزرگتر از این خواهد بود، حتی بیشتر با استفاده از استقرار سایه/سایه jar. اگر jar ها را با دست اجرا کنید، ممکن است با خطاهایی مانند:

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])

در عوض، با استفاده از پلاگین AppEngine Gradle یا افزونه Maven مستقر شوید. هر کدام گزینه ای برای enableJarSplitting دارند که هر شیشه را به تکه های 10 مگابایتی تقسیم می کند و در عوض آن ها را آپلود می کند.

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

اگر پروژه شما دارای وابستگی هایی است که با کتابخانه در تضاد هستند، باید وابستگی های پروژه خود را با استفاده از یکی از دستورات زیر بررسی کنید، سپس وابستگی های پروژه خود را در صورت نیاز تغییر دهید.

ماون

mvn dependency:tree

گریدل

./gradlew dependencies

اگر حل تعارضات وابستگی غیرممکن است، می‌توانید در عوض به نسخه سایه‌دار کتابخانه تکیه کنید.

ماون

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

گریدل

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