درخواست های دسته ای

این سند نشان می‌دهد که چگونه فراخوانی‌های API را دسته بندی کنید تا تعداد اتصالات HTTP که کلاینت شما باید برقرار کند را کاهش دهید.

این سند به طور خاص در مورد ایجاد درخواست دسته‌ای با ارسال درخواست HTTP است. اگر به جای آن، از یک کتابخانه کلاینت گوگل برای ایجاد درخواست دسته‌ای استفاده می‌کنید، به مستندات کتابخانه کلاینت مراجعه کنید.

نمای کلی

هر اتصال HTTP که کلاینت شما برقرار می‌کند، منجر به مقدار مشخصی سربار می‌شود. API مرکز تولیدکننده از دسته‌بندی پشتیبانی می‌کند تا به کلاینت شما اجازه دهد چندین فراخوانی API را در یک درخواست HTTP واحد قرار دهد.

نمونه‌هایی از موقعیت‌هایی که ممکن است بخواهید از دسته‌بندی استفاده کنید:

• بارگذاری تعداد زیادی محصول.

• حذف تعداد زیادی از محصولات

• بازیابی تعداد زیادی از محصولات.

در هر مورد، به جای ارسال جداگانه هر فراخوانی، می‌توانید آنها را در یک درخواست HTTP واحد گروه‌بندی کنید. همه درخواست‌های داخلی باید به یک API گوگل یکسان بروند.

شما در یک درخواست دسته‌ای محدود به ۱۰۰۰ تماس هستید. اگر مجبور به برقراری تماس‌های بیشتر از این هستید، از درخواست‌های دسته‌ای چندگانه استفاده کنید.

نکته : سیستم دسته‌ای برای API مرکز تولیدکننده از همان سینتکس سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معانی آن متفاوت است.

جزئیات دسته‌ای

یک درخواست دسته‌ای شامل چندین فراخوانی API است که در قالب یک درخواست HTTP ترکیب شده‌اند و می‌توانند به batchPath مشخص شده در سند کشف API ارسال شوند. مسیر پیش‌فرض /batch/ api_name / api_version است. این بخش سینتکس دسته‌ای را با جزئیات شرح می‌دهد؛ بعداً، یک مثال وجود دارد.

توجه : مجموعه‌ای از n درخواست که با هم دسته‌بندی شده‌اند، به عنوان n درخواست در محدودیت استفاده شما محاسبه می‌شوند، نه به عنوان یک درخواست. درخواست دسته‌ای قبل از پردازش به مجموعه‌ای از درخواست‌ها تقسیم می‌شود.

قالب درخواست دسته‌ای

یک درخواست دسته‌ای، یک درخواست HTTP استاندارد واحد است که شامل چندین فراخوانی API مرکز تولیدکننده است و از نوع محتوای multipart/mixed استفاده می‌کند. در آن درخواست HTTP اصلی، هر یک از بخش‌ها شامل یک درخواست HTTP تو در تو هستند.

هر بخش با هدر Content-Type: application/http HTTP مخصوص به خود شروع می‌شود. همچنین می‌تواند یک هدر Content-ID اختیاری داشته باشد. با این حال، هدرهای بخش فقط برای مشخص کردن شروع بخش وجود دارند؛ آنها از درخواست تو در تو جدا هستند. پس از اینکه سرور درخواست دسته‌ای را به درخواست‌های جداگانه تجزیه می‌کند، هدرهای بخش نادیده گرفته می‌شوند.

بدنه هر بخش، یک درخواست HTTP کامل است که فعل، URL، هدرها و بدنه مخصوص به خود را دارد. درخواست HTTP فقط باید شامل بخش مسیر URL باشد؛ URL های کامل در درخواست های دسته ای مجاز نیستند.

هدرهای HTTP برای درخواست دسته‌ای بیرونی، به جز هدرهای Content- مانند Content-Type ، برای هر درخواست در دسته اعمال می‌شوند. اگر یک هدر HTTP مشخص را هم در درخواست بیرونی و هم در یک فراخوانی جداگانه مشخص کنید، مقدار هدر فراخوانی جداگانه، مقدار هدر درخواست دسته‌ای بیرونی را لغو می‌کند. هدرهای یک فراخوانی جداگانه فقط برای آن فراخوانی اعمال می‌شوند.

برای مثال، اگر برای یک فراخوانی خاص، یک هدر مجوز (Authorization header) ارائه دهید، آن هدر فقط برای همان فراخوانی اعمال می‌شود. اگر برای درخواست بیرونی، یک هدر مجوز (Authorization header) ارائه دهید، آن هدر برای تمام فراخوانی‌های منفرد اعمال می‌شود، مگر اینکه آنها با هدرهای مجوز (Authorization header) خودشان، آن را لغو کنند.

وقتی سرور درخواست دسته‌ای را دریافت می‌کند، پارامترها و هدرهای درخواست بیرونی (به تناسب) را برای هر بخش اعمال می‌کند و سپس با هر بخش مانند یک درخواست HTTP جداگانه رفتار می‌کند.

پاسخ به درخواست دسته‌ای

پاسخ سرور، یک پاسخ استاندارد HTTP با نوع محتوای multipart/mixed است؛ هر بخش، پاسخ به یکی از درخواست‌های موجود در درخواست دسته‌ای، به همان ترتیب درخواست‌ها، می‌باشد.

مانند بخش‌های درخواست، هر بخش پاسخ شامل یک پاسخ کامل HTTP، شامل کد وضعیت، هدرها و بدنه است. و مانند بخش‌های درخواست، قبل از هر بخش پاسخ، یک هدر Content-Type قرار دارد که ابتدای بخش را مشخص می‌کند.

اگر بخش مشخصی از درخواست دارای سرآیند Content-ID باشد، بخش متناظر پاسخ نیز دارای سرآیند Content-ID منطبق با آن است که مقدار اصلی آن قبل از رشته response- قرار می‌گیرد، همانطور که در مثال زیر نشان داده شده است.

توجه : سرور ممکن است فراخوانی‌های شما را به هر ترتیبی انجام دهد. روی اجرای آنها به ترتیبی که شما مشخص کرده‌اید حساب نکنید. اگر می‌خواهید مطمئن شوید که دو فراخوانی به ترتیب مشخصی انجام می‌شوند، نمی‌توانید آنها را در یک درخواست واحد ارسال کنید. در عوض، اولی را به تنهایی ارسال کنید، سپس قبل از ارسال دومی منتظر پاسخ اولی باشید.

مثال

مثال زیر استفاده از دسته بندی با رابط برنامه‌نویسی کاربردی مرکز تولیدکنندگان (Manager Center API) را نشان می‌دهد.

مثال درخواست دسته‌ای

POST https://manufacturers.googleapis.com/batch
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary=--batch_item

--batch_item
Content-Type: application/http
Content-ID: 

PUT /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
Content-Type: application/json

{
   "gtin": "gtin",
   "product_name": "product_name",
   "description": "description",
   "image_link": {
       "image_url": "image_url"
   }
}
--batch_item
Content-Type: application/http
Content-ID: 

GET /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
--batch_item
Content-Type: application/http
Content-ID: 

DELETE /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
--batch_item--

مثال پاسخ دسته‌ای

این پاسخ به درخواست نمونه در بخش قبلی است.

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{
  "parent": "accounts/account_id",
  "name": "targetCountry:contentLanguage:productId",
  "targetCountry": "targetCountry",
  "contentLanguage": "contentLanguage",
  "productId": "productId"
}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa--

پیش‌نیازها

حساب کاربری مرکز تولیدکنندگان

مثال دسته‌ای

کد زیر نحوه ارسال به‌روزرسانی‌های محصول به صورت دسته‌ای با استفاده از جاوا را نشان می‌دهد.

جاوا

String parent = "accounts/123456";
String newProductName = "US:en:product_id_1";

Image image = new Image();
image.setUrl("http://www.example.com/example.png");

Attributes attributes = new Attributes();
attributes.setGtin(ImmmutableList.of("1234567890"));
attributes.setImageLink(image);

// Creates a new BatchRequest object from the ManufacturerCenter object.
BatchRequest batch = manufacturerCenter.batch();

// JsonBatchCallback generic type is Empty to match the return type of update API.
JsonBatchCallback updateProductCallback =  new JsonBatchCallback() {
    public void onSuccess(Empty empty, HttpHeaders responseHeaders) {
        System.out.printf("Product updated successfully.\n");
    }

    public void onFailure(GoogleJsonError error, HttpHeaders responseHeaders)
            throws IOException {
        System.out.printf("Error updating product: %s.\n", error.getMessage());
    }
}

// Adds update product request to batch object.
manufacturerCenter.accounts().products().update(parent, newProductName, attributes)
    .queue(batch, updateProductCallback);

String getProductName = "US:en:product_id_2";

// JsonBatchCallback generic type is Product to match the return type of get API.
JsonBatchCallback getProductCallback =  new JsonBatchCallback() {
    public void onSuccess(Product product, HttpHeaders responseHeaders) {
        System.out.printf("Found product: %s.\n", product.getName());
    }

    public void onFailure(GoogleJsonError error, HttpHeaders responseHeaders)
            throws IOException {
        System.out.printf("Error retrieving product: %s.\n", error.getMessage());
    }
}

// Adds get product request to batch object.
manufacturerCenter.accounts().products().get(parent, getProductName)
    .queue(batch, getProductCallback);

// Sends batch request to Manufacturer Center API.
batch.execute();