التنفيذ: الردود الجزئية

توضّح الأمثلة التالية كيفية استرداد ردود جزئية من واجهة برمجة التطبيقات في YouTube Data API (الإصدار 3).

ملاحظة: يقدّم دليل البدء لواجهة برمجة التطبيقات مزيدًا من التفاصيل حول الطلبات والردود الجزئية.

تسمح وتطلب v3 API استرداد الموارد الجزئية كي تتجنب التطبيقات نقل البيانات غير المطلوبة وتحليلها وتخزينها. يضمن هذا النهج أيضًا أن تستخدم واجهة برمجة التطبيقات موارد الشبكة ووحدة المعالجة المركزية والذاكرة بكفاءة أكبر.

تتيح لك واجهة برمجة التطبيقات معلمتَي طلب، وهما part وfields، تتيحان لك تحديد سمات الموارد التي يجب تضمينها في استجابات واجهة برمجة التطبيقات. وتحدِّد المَعلمة part أيضًا السمات التي يجب ضبطها من خلال طلبات البيانات من واجهة برمجة التطبيقات التي تُدرج الموارد أو تعدّلها.

يُرجى العِلم أنّه إذا لم يحدّد طلب التعديل قيمة لسمة مورد كانت لها قيمة في السابق، سيتم حذف القيمة الحالية إذا كانت الشروط التالية صحيحة:

• يمكن تعديل قيمة السمة من خلال الطلب. (على سبيل المثال، عند تعديل مورد video، يمكنك تعديل قيمة السمة snippet.description، ولكن لا يمكنك تعديل قيمة العنصر snippet.thumbnails.

• تحدِّد قيمة المَعلمة part في الطلب جزء المورد الذي يحتوي على السمة.

مثال

على سبيل المثال، لنفترض أنّك تريد تعديل مرجع video الظاهر أدناه. (يُرجى العِلم أنّه يمكن تعديل جميع السمات الموضّحة أدناه من خلال واجهة برمجة التطبيقات، وتم حذف سمات الموارد غير ذات الصلة بالمثال).

{
  "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. يحتوي نص طلب واجهة برمجة التطبيقات على المرجع التالي:

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

يؤدي هذا الطلب إلى تعديل عنوان الفيديو وحذف وصفه، ولا يؤدي إلى تغيير علاماته أو رقم تعريف الفئة. يتم حذف وصف الفيديو لأنّ الطلب لا يحدّد قيمة للسمة snippet.description.

لا تتأثر الخصائص في عنصر status على الإطلاق لأنّ قيمة المَعلمة part لم تتضمّن status كأحد الأجزاء التي سيُجري الطلب تعديلات عليها. في الواقع، إذا كان نص طلب بيانات واجهة برمجة التطبيقات يتضمّن العنصر status، ستعرض واجهة برمجة التطبيقات استجابة HTTP‏ 400 (Bad Request) بسبب تضمين جزء غير متوقّع في نص الطلب.