این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

بهبود کارایی

این سند برخی از تکنیک ها را پوشش می دهد که می توانید برای بهبود عملکرد برنامه خود از آنها استفاده کنید. در برخی موارد، نمونه هایی از سایر APIها یا APIهای عمومی برای نشان دادن ایده های ارائه شده استفاده می شود. با این حال، همان مفاهیم برای Google Drive API قابل اعمال است.

فشرده سازی با استفاده از gzip

یک راه آسان و راحت برای کاهش پهنای باند مورد نیاز برای هر درخواست، فعال کردن فشرده‌سازی gzip است. اگرچه این امر به زمان اضافی CPU برای فشرده سازی نتایج نیاز دارد، اما معاوضه با هزینه های شبکه معمولاً آن را بسیار ارزشمند می کند.

برای دریافت پاسخ کدگذاری شده با gzip، باید دو کار انجام دهید: یک هدر Accept-Encoding تنظیم کنید، و عامل کاربری خود را طوری تغییر دهید که شامل رشته gzip باشد. در اینجا نمونه ای از هدرهای HTTP که به درستی شکل گرفته اند برای فعال کردن فشرده سازی gzip آورده شده است:

Accept-Encoding: gzip
User-Agent: my program (gzip)

کار با منابع جزئی

راه دیگر برای بهبود عملکرد تماس‌های API، ارسال و دریافت تنها بخشی از داده‌هایی است که به آن‌ها علاقه دارید. این به برنامه شما امکان می‌دهد از انتقال، تجزیه و ذخیره فیلدهای غیر ضروری جلوگیری کند، بنابراین می‌تواند از منابعی از جمله شبکه استفاده کند. CPU و حافظه کارآمدتر.

دو نوع درخواست جزئی وجود دارد:

پاسخ جزئی : درخواستی که در آن مشخص می‌کنید کدام فیلدها در پاسخ گنجانده شوند (از پارامتر درخواست fields استفاده کنید).
Patch : یک درخواست به روز رسانی که در آن فقط فیلدهایی را که می خواهید تغییر دهید ارسال می کنید (از فعل PATCH HTTP استفاده کنید).

جزئیات بیشتر در مورد درخواست های جزئی در بخش های بعدی ارائه شده است.

پاسخ نسبی

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

برای درخواست پاسخ جزئی، از پارامتر درخواست fields استفاده کنید تا فیلدهایی را که می خواهید برگردانید مشخص کنید. می توانید از این پارامتر با هر درخواستی که داده های پاسخ را برمی گرداند استفاده کنید.

توجه داشته باشید که پارامتر fields فقط بر داده‌های پاسخ تأثیر می‌گذارد. بر روی داده هایی که باید ارسال کنید، در صورت وجود، تأثیری نمی گذارد. برای کاهش حجم داده‌ای که هنگام اصلاح منابع ارسال می‌کنید، از درخواست وصله استفاده کنید.

مثال

مثال زیر استفاده از پارامتر fields را با یک API "دمو" عمومی (تخیلی) نشان می دهد.

درخواست ساده: این درخواست HTTP GET پارامتر fields حذف می کند و منبع کامل را برمی گرداند.

https://www.googleapis.com/demo/v1

پاسخ منبع کامل: داده‌های کامل منبع شامل فیلدهای زیر است، همراه با بسیاری دیگر که برای اختصار حذف شده‌اند.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

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

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

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

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

توجه داشته باشید که پاسخ یک شی JSON است که فقط شامل فیلدهای انتخاب شده و اشیاء والد محصور آنها می شود.

جزئیات در مورد نحوه قالب بندی پارامتر fields در ادامه پوشش داده می شود و به دنبال آن جزئیات بیشتری در مورد آنچه دقیقاً در پاسخ برگردانده می شود، ارائه می شود.

خلاصه نحو پارامتر فیلدها

فرمت مقدار پارامتر درخواست fields بر اساس نحو XPath است. نحو پشتیبانی شده در زیر خلاصه شده است و نمونه های اضافی در بخش زیر ارائه شده است.

از یک لیست جدا شده با کاما برای انتخاب چندین فیلد استفاده کنید.
از a/b برای انتخاب فیلد b که در فیلد a تودرتو است استفاده کنید. از a/b/c برای انتخاب یک فیلد c تو در تو در b استفاده کنید.
استثنا: برای پاسخ‌های API که از بسته‌بندی‌های «داده» استفاده می‌کنند، که در آن پاسخ درون یک شی data که شبیه data: { ... } ، « data » را در مشخصات fields لحاظ نکنید. گنجاندن شی داده با مشخصات فیلدهایی مانند data/a/b باعث ایجاد خطا می شود. در عوض، فقط از مشخصات fields مانند a/b استفاده کنید.
از یک انتخابگر فرعی برای درخواست مجموعه ای از فیلدهای فرعی خاص از آرایه ها یا اشیاء با قرار دادن عبارات در پرانتز " ( ) " استفاده کنید.
برای مثال: fields=items(id,author/email) فقط شناسه مورد و ایمیل نویسنده را برای هر عنصر در آرایه آیتم ها برمی گرداند. شما همچنین می توانید یک زیر فیلد را مشخص کنید که در آن fields=items(id) معادل fields=items/id باشد.
در صورت نیاز از حروف عام در انتخاب زمینه استفاده کنید.
به عنوان مثال: fields=items/pagemap/* تمام اشیاء موجود در نقشه صفحه را انتخاب می کند.

نمونه های بیشتری از استفاده از پارامتر فیلدها

مثال‌های زیر شامل توضیحاتی در مورد چگونگی تأثیر مقدار پارامتر fields بر پاسخ است.

توجه: مانند تمام مقادیر پارامتر پرس و جو، مقدار پارامتر fields باید URL کدگذاری شده باشد. برای خوانایی بهتر، مثال های این سند رمزگذاری را حذف کرده اند.

فیلدهایی را که می خواهید برگردانید شناسایی کنید یا فیلدهایی را انتخاب کنید.

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

در اینجا چند نمونه در سطح مجموعه آورده شده است:

نمونه ها	اثر
`items`	همه عناصر موجود در آرایه آیتم ها، از جمله تمام فیلدهای هر عنصر، اما هیچ فیلد دیگری را برمی گرداند.
`etag,items`	هم فیلد `etag` و هم همه عناصر موجود در آرایه آیتم ها را برمی گرداند.
`items/title`	فقط فیلد `title` برای همه عناصر موجود در آرایه آیتم ها برمی گرداند. هر زمان که یک فیلد تودرتو برگردانده شود، پاسخ شامل اشیاء والد محصور می شود. فیلدهای والد هیچ فیلد فرزند دیگری را شامل نمی شود مگر اینکه آنها نیز صریحاً انتخاب شده باشند.
`context/facets/label`	فقط فیلد `label` برای همه اعضای آرایه `facets` برمی‌گرداند که خود در زیر شیء `context` قرار دارد.
`items/pagemap/*/title`	برای هر عنصر در آرایه آیتم‌ها، فقط فیلد `title` (در صورت وجود) همه اشیایی را که فرزندان `pagemap` هستند برمی‌گرداند.

در اینجا چند نمونه در سطح منبع آورده شده است:

نمونه ها	اثر
`title`	فیلد `title` منبع درخواستی را برمی گرداند.
`author/uri`	فیلد فرعی `uri` شی `author` را در منبع درخواستی برمی گرداند.
`links/*/href`	فیلد `href` همه اشیایی که فرزند `links` هستند را برمی گرداند.

فقط بخش‌هایی از فیلدهای خاص را با استفاده از انتخاب‌های فرعی درخواست کنید.

به طور پیش فرض، اگر درخواست شما فیلدهای خاصی را مشخص کند، سرور اشیاء یا عناصر آرایه را به طور کامل برمی گرداند. می توانید پاسخی را مشخص کنید که فقط شامل قسمت های فرعی خاصی باشد. شما این کار را با استفاده از نحو انتخاب فرعی " ( ) " مانند مثال زیر انجام می دهید.

مثال	اثر
`items(title,author/uri)`	فقط مقادیر `title` و `uri` نویسنده را برای هر عنصر در آرایه آیتم ها برمی گرداند.

رسیدگی به پاسخ های جزئی

پس از اینکه سرور یک درخواست معتبر که شامل پارامتر پرس و جو fields است را پردازش کرد، یک کد وضعیت HTTP 200 OK را به همراه داده های درخواستی ارسال می کند. اگر پارامتر پرس و جو fields دارای خطا باشد یا در غیر این صورت نامعتبر باشد، سرور یک کد وضعیت 400 Bad Request را به همراه یک پیام خطایی که به کاربر می‌گوید در انتخاب فیلدهایش چه مشکلی داشته است (به عنوان مثال، "Invalid field selection a/b" . "Invalid field selection a/b" ).

در اینجا نمونه پاسخ جزئی نشان داده شده در بخش مقدماتی بالا است. درخواست از پارامتر fields برای تعیین اینکه کدام فیلدها را برگرداند استفاده می کند.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

پاسخ جزئی به این صورت است:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

توجه: برای APIهایی که از پارامترهای پرس و جو برای صفحه بندی داده ها پشتیبانی می کنند (مثلاً maxResults و nextPageToken )، از این پارامترها برای کاهش نتایج هر پرس و جو به اندازه قابل مدیریت استفاده کنید. در غیر این صورت، افزایش عملکرد ممکن با پاسخ نسبی ممکن است محقق نشود.

پچ (به روز رسانی جزئی)

همچنین می توانید هنگام اصلاح منابع از ارسال داده های غیر ضروری خودداری کنید. برای ارسال داده های به روز شده فقط برای فیلدهای خاصی که در حال تغییر آن هستید، از فعل HTTP PATCH استفاده کنید. معانی وصله‌ای که در این سند توضیح داده شده است متفاوت (و ساده‌تر) نسبت به اجرای قدیمی‌تر GData از به‌روزرسانی جزئی است.

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

مثال

این مثال یک درخواست وصله ساده را نشان می دهد تا فقط عنوان یک منبع API "دمو" عمومی (تخیلی) را به روز کند. این منبع همچنین دارای یک نظر، مجموعه‌ای از ویژگی‌ها، وضعیت و بسیاری فیلدهای دیگر است، اما این درخواست فقط فیلد title را ارسال می‌کند، زیرا این تنها فیلدی است که اصلاح می‌شود:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

پاسخ:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

سرور یک کد وضعیت 200 OK را به همراه نمایش کامل منبع به روز شده برمی گرداند. از آنجایی که فقط قسمت title در درخواست وصله گنجانده شده است، این تنها مقداری است که با قبل متفاوت است.

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

معناشناسی درخواست پچ

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

افزودن: برای افزودن فیلدی که قبلاً وجود ندارد، فیلد جدید و مقدار آن را مشخص کنید.
Modify: برای تغییر مقدار یک فیلد موجود، فیلد را مشخص کرده و آن را به مقدار جدید تنظیم کنید.
حذف: برای حذف یک فیلد، فیلد را مشخص کرده و آن را روی null قرار دهید. به عنوان مثال، "comment": null . همچنین می توانید کل یک شی (اگر قابل تغییر باشد) را با تنظیم آن بر روی null حذف کنید. اگر از Java API Client Library استفاده می کنید، به جای آن از Data.NULL_STRING استفاده کنید. برای جزئیات، JSON null را ببینید.

نکته در مورد آرایه ها: درخواست های وصله ای که حاوی آرایه هستند، آرایه موجود را با آرایه ای که ارائه می کنید جایگزین می کند. شما نمی توانید موارد را در یک آرایه به صورت تکه ای تغییر، اضافه یا حذف کنید.

استفاده از وصله در چرخه خواندن، اصلاح و نوشتن

این می تواند تمرین مفیدی باشد که با بازیابی یک پاسخ جزئی با داده هایی که می خواهید تغییر دهید شروع کنید. این امر به ویژه برای منابعی که از ETags استفاده می‌کنند مهم است، زیرا برای به‌روزرسانی موفقیت‌آمیز منبع، باید مقدار ETag فعلی را در هدر HTTP If-Match ارائه دهید. پس از دریافت داده‌ها، می‌توانید مقادیری را که می‌خواهید تغییر دهید تغییر دهید و نمایش جزئی اصلاح شده را با یک درخواست وصله ارسال کنید. در اینجا مثالی وجود دارد که فرض می کند منبع دمو از ETags استفاده می کند:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

این پاسخ جزئی است:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

درخواست پچ زیر بر اساس آن پاسخ است. همانطور که در زیر نشان داده شده است، از پارامتر fields نیز برای محدود کردن داده های بازگشتی در پاسخ وصله استفاده می کند:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

سرور با یک کد وضعیت HTTP 200 OK و نمایش بخشی از منبع به روز شده پاسخ می دهد:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

ساخت درخواست پچ به طور مستقیم

برای برخی از درخواست‌های وصله، باید آنها را بر اساس داده‌هایی که قبلاً بازیابی کرده‌اید، قرار دهید. به عنوان مثال، اگر می خواهید یک آیتم را به یک آرایه اضافه کنید و نمی خواهید هیچ یک از عناصر آرایه موجود را از دست بدهید، ابتدا باید داده های موجود را دریافت کنید. به طور مشابه، اگر یک API از ETags استفاده می کند، باید مقدار ETag قبلی را همراه با درخواست خود ارسال کنید تا منبع با موفقیت به روز شود.

توجه: می‌توانید از هدر HTTP "If-Match: *" برای وادار کردن یک وصله در هنگام استفاده از تگ‌های ET استفاده کنید. اگر این کار را انجام دهید، نیازی به خواندن قبل از نوشتن ندارید.

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

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

با این درخواست، اگر فیلد نظر دارای یک مقدار موجود باشد، مقدار جدید آن را بازنویسی می کند. در غیر این صورت به مقدار جدید تنظیم می شود. به طور مشابه، اگر مشخصه حجمی وجود داشته باشد، مقدار آن بازنویسی می شود. اگر نه، ایجاد می شود. فیلد دقت، در صورت تنظیم، حذف می شود.

مدیریت پاسخ به یک پچ

پس از پردازش یک درخواست پچ معتبر، API یک کد پاسخ HTTP 200 OK را همراه با نمایش کامل منبع اصلاح شده برمی گرداند. اگر ETag ها توسط API استفاده شوند، سرور مقادیر ETag را هنگامی که با موفقیت یک درخواست وصله را پردازش می کند، به روز می کند، درست مانند PUT .

درخواست وصله کل نمایش منبع را برمی گرداند مگر اینکه از پارامتر fields برای کاهش مقدار داده ای که برمی گرداند استفاده کنید.

اگر یک درخواست وصله منجر به یک وضعیت منبع جدید شود که از نظر نحوی یا معنایی نامعتبر است، سرور یک کد وضعیت HTTP 400 Bad Request یا 422 Unprocessable Entity را برمی گرداند و وضعیت منبع بدون تغییر باقی می ماند. به عنوان مثال، اگر سعی کنید مقدار یک فیلد ضروری را حذف کنید، سرور یک خطا را برمی‌گرداند.

هنگامی که فعل HTTP PATCH پشتیبانی نمی شود، نماد جایگزین کنید

اگر فایروال شما اجازه درخواست HTTP PATCH را نمی دهد، یک درخواست HTTP POST انجام دهید و هدر override را روی PATCH تنظیم کنید، مانند شکل زیر:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

تفاوت پچ و آپدیت

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

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

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

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

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

نمای کلی

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

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

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

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

شما به 100 تماس در یک درخواست دسته‌ای محدود می‌شوید. اگر باید بیشتر از آن تماس بگیرید، از چندین درخواست دسته ای استفاده کنید.

توجه : سیستم دسته‌ای برای Google Drive API از نحوی مشابه با سیستم پردازش دسته‌ای OData استفاده می‌کند، اما معنایی متفاوت است.

محدودیت های اضافی عبارتند از:

درخواست های دسته ای با بیش از 100 تماس ممکن است باعث خطا شوند.
یک محدودیت 8000 کاراکتری در طول URL برای هر درخواست داخلی وجود دارد.
Google Drive از عملیات دسته‌ای برای رسانه، چه برای آپلود یا دانلود، یا برای صادر کردن فایل‌ها پشتیبانی نمی‌کند.

جزئیات دسته

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

مثال زیر استفاده از دسته‌بندی با Google Drive API را نشان می‌دهد.

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

POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963

--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8

{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8

{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--

نمونه پاسخ دسته ای

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

HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "12218244892818058021i" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "04109509152946699072k" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk--

فیلدهای خاص را از درخواست برگردانید

به طور پیش‌فرض، سرور مجموعه‌ای از فیلدهای منابع پیش‌فرض را به روش مورد استفاده برمی‌گرداند. برای مثال، روش files.list ممکن است فقط id ، name و mimeType را برگرداند. ممکن است این فیلدها دقیقاً فیلدهای مورد نیاز شما نباشند. اگر نیاز به برگرداندن سایر فیلدها دارید، به بازگشت فیلدهای خاص برای یک فایل مراجعه کنید.

فشرده سازی با استفاده از gzip

Accept-Encoding: gzip
User-Agent: my program (gzip)

کار با منابع جزئی

دو نوع درخواست جزئی وجود دارد:

پاسخ جزئی : درخواستی که در آن مشخص می‌کنید کدام فیلدها در پاسخ گنجانده شوند (از پارامتر درخواست fields استفاده کنید).
Patch : یک درخواست به روز رسانی که در آن فقط فیلدهایی را که می خواهید تغییر دهید ارسال می کنید (از فعل PATCH HTTP استفاده کنید).

جزئیات بیشتر در مورد درخواست های جزئی در بخش های بعدی ارائه شده است.

پاسخ نسبی

مثال

مثال زیر استفاده از پارامتر fields را با یک API "دمو" عمومی (تخیلی) نشان می دهد.

درخواست ساده: این درخواست HTTP GET پارامتر fields حذف می کند و منبع کامل را برمی گرداند.

https://www.googleapis.com/demo/v1

پاسخ منبع کامل: داده‌های کامل منبع شامل فیلدهای زیر است، همراه با بسیاری دیگر که برای اختصار حذف شده‌اند.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

توجه داشته باشید که پاسخ یک شی JSON است که فقط شامل فیلدهای انتخاب شده و اشیاء والد محصور آنها می شود.

خلاصه نحو پارامتر فیلدها

از یک لیست جدا شده با کاما برای انتخاب چندین فیلد استفاده کنید.
از a/b برای انتخاب فیلد b که در فیلد a تودرتو است استفاده کنید. از a/b/c برای انتخاب یک فیلد c تو در تو در b استفاده کنید.
استثنا: برای پاسخ‌های API که از بسته‌بندی‌های «داده» استفاده می‌کنند، که در آن پاسخ درون یک شی data که شبیه data: { ... } ، « data » را در مشخصات fields لحاظ نکنید. گنجاندن شی داده با مشخصات فیلدهایی مانند data/a/b باعث ایجاد خطا می شود. در عوض، فقط از مشخصات fields مانند a/b استفاده کنید.
از یک انتخابگر فرعی برای درخواست مجموعه ای از فیلدهای فرعی خاص از آرایه ها یا اشیاء با قرار دادن عبارات در پرانتز " ( ) " استفاده کنید.
برای مثال: fields=items(id,author/email) فقط شناسه مورد و ایمیل نویسنده را برای هر عنصر در آرایه آیتم ها برمی گرداند. شما همچنین می توانید یک زیر فیلد را مشخص کنید که در آن fields=items(id) معادل fields=items/id باشد.
در صورت نیاز از حروف عام در انتخاب زمینه استفاده کنید.
به عنوان مثال: fields=items/pagemap/* تمام اشیاء موجود در نقشه صفحه را انتخاب می کند.

نمونه های بیشتری از استفاده از پارامتر فیلدها

مثال‌های زیر شامل توضیحاتی در مورد چگونگی تأثیر مقدار پارامتر fields بر پاسخ است.

فیلدهایی را که می خواهید برگردانید شناسایی کنید یا فیلدهایی را انتخاب کنید.

نمونه ها	اثر
`items`	همه عناصر موجود در آرایه آیتم ها، از جمله تمام فیلدهای هر عنصر، اما هیچ فیلد دیگری را برمی گرداند.
`etag,items`	هم فیلد `etag` و هم همه عناصر موجود در آرایه آیتم ها را برمی گرداند.
`items/title`	فقط فیلد `title` برای همه عناصر موجود در آرایه آیتم ها برمی گرداند. هر زمان که یک فیلد تودرتو برگردانده شود، پاسخ شامل اشیاء والد محصور می شود. فیلدهای والد هیچ فیلد فرزند دیگری را شامل نمی شود مگر اینکه آنها نیز صریحاً انتخاب شده باشند.
`context/facets/label`	فقط فیلد `label` برای همه اعضای آرایه `facets` برمی‌گرداند که خود در زیر شیء `context` قرار دارد.
`items/pagemap/*/title`	برای هر عنصر در آرایه آیتم‌ها، فقط فیلد `title` (در صورت وجود) همه اشیایی را که فرزندان `pagemap` هستند برمی‌گرداند.

در اینجا چند نمونه در سطح منبع آورده شده است:

نمونه ها	اثر
`title`	فیلد `title` منبع درخواستی را برمی گرداند.
`author/uri`	فیلد فرعی `uri` شی `author` را در منبع درخواستی برمی گرداند.
`links/*/href`	فیلد `href` همه اشیایی که فرزند `links` هستند را برمی گرداند.

فقط بخش‌هایی از فیلدهای خاص را با استفاده از انتخاب‌های فرعی درخواست کنید.

مثال	اثر
`items(title,author/uri)`	فقط مقادیر `title` و `uri` نویسنده را برای هر عنصر در آرایه آیتم ها برمی گرداند.

رسیدگی به پاسخ های جزئی

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

پاسخ جزئی به این صورت است:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

پچ (به روز رسانی جزئی)

مثال

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

پاسخ:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

معناشناسی درخواست پچ

افزودن: برای افزودن فیلدی که قبلاً وجود ندارد، فیلد جدید و مقدار آن را مشخص کنید.
Modify: برای تغییر مقدار یک فیلد موجود، فیلد را مشخص کرده و آن را به مقدار جدید تنظیم کنید.
حذف: برای حذف یک فیلد، فیلد را مشخص کرده و آن را روی null قرار دهید. به عنوان مثال، "comment": null . همچنین می توانید کل یک شی (اگر قابل تغییر باشد) را با تنظیم آن بر روی null حذف کنید. اگر از Java API Client Library استفاده می کنید، به جای آن از Data.NULL_STRING استفاده کنید. برای جزئیات، JSON null را ببینید.

استفاده از وصله در چرخه خواندن، اصلاح و نوشتن

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

این پاسخ جزئی است:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

سرور با یک کد وضعیت HTTP 200 OK و نمایش بخشی از منبع به روز شده پاسخ می دهد:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

ساخت درخواست پچ به طور مستقیم

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

مدیریت پاسخ به یک پچ

هنگامی که فعل HTTP PATCH پشتیبانی نمی شود، نماد جایگزین کنید

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

تفاوت پچ و آپدیت

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

نمای کلی

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

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

محدودیت های اضافی عبارتند از:

درخواست های دسته ای با بیش از 100 تماس ممکن است باعث خطا شوند.
یک محدودیت 8000 کاراکتری در طول URL برای هر درخواست داخلی وجود دارد.
Google Drive از عملیات دسته‌ای برای رسانه، چه برای آپلود یا دانلود، یا برای صادر کردن فایل‌ها پشتیبانی نمی‌کند.

جزئیات دسته

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

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

مثال

مثال زیر استفاده از دسته‌بندی با Google Drive API را نشان می‌دهد.

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

POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963

--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8

{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary

{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--

نمونه پاسخ دسته ای

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

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "12218244892818058021i" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "04109509152946699072k" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk--