پیاده سازی: پاسخ های جزئی

مثال‌های زیر نحوه بازیابی پاسخ‌های API جزئی در YouTube Data API (v3) را نشان می‌دهند.

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

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

API از دو پارامتر درخواست، part و fields پشتیبانی می‌کند که به شما امکان می‌دهد ویژگی‌های منبعی را که باید در پاسخ‌های API گنجانده شوند، شناسایی کنید. پارامتر part همچنین ویژگی هایی را که باید توسط درخواست های API که منابع درج یا به روز می کنند تنظیم شوند، مشخص می کند.

توجه داشته باشید که اگر یک درخواست به‌روزرسانی مقداری را برای ویژگی منبعی که قبلاً دارای مقدار بوده است مشخص نکند، در صورت درست بودن شرایط زیر، مقدار موجود حذف می‌شود:

• ارزش ملک را می توان با درخواست تغییر داد. (به عنوان مثال، هنگام به روز رسانی یک منبع video ، می توانید مقدار ویژگی snippet.description را به روز کنید، اما نمی توانید مقدار شی snippet.thumbnails را به روز کنید.

• مقدار پارامتر part درخواست، بخشی از منبع را که دارای ویژگی است مشخص می کند.

مثال

به عنوان مثال، فرض کنید می خواهید منبع video نشان داده شده در زیر را به روز کنید. (توجه داشته باشید که تمام ویژگی های نشان داده شده در زیر می توانند از طریق API به روز شوند و ویژگی های منبع غیر مرتبط با مثال حذف شده اند.)

{
  "snippet": {
    "title": "Old video title",
    "description": "Old video description",
    "tags": ["keyword1","keyword2","keyword3"],
    "categoryId: 22
  },
  "status": {
    "privacyStatus": "private",
    "publishAt": "2014-09-01T12:00:00.0Z",
    "license": "youtube",
    "embeddable": True,
    "publicStatsViewable": True
  }
}

شما متد videos.update را فراخوانی می‌کنید و مقدار پارامتر part را روی snippet تنظیم می‌کنید. بدنه درخواست API حاوی منبع زیر است:

{
  "snippet": {
    "title": "New video title",
    "tags": ["keyword1","keyword2","keyword3"],
    "categoryId: 22
  }
}

این درخواست عنوان ویدیو را به‌روزرسانی می‌کند، توضیحات آن را حذف می‌کند و برچسب‌ها یا شناسه دسته آن را تغییر نمی‌دهد. توضیحات ویدیو حذف شده است زیرا درخواست مقداری برای ویژگی snippet.description مشخص نمی کند.

ویژگی‌های موجود در شی status اصلاً تحت تأثیر قرار نمی‌گیرند زیرا مقدار پارامتر part status به عنوان یکی از بخش‌هایی که درخواست به‌روزرسانی می‌کند، شامل نمی‌شود. در واقع، اگر بدنه درخواست API شامل شی status باشد، API یک پاسخ HTTP 400 (Bad Request) به دلیل وجود بخشی غیرمنتظره در بدنه درخواست برمی‌گرداند.