فیلدهای خاص را برگردانید

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

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

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

پس از اینکه سرور یک درخواست معتبر را که شامل پارامتر fields است پردازش کرد، یک کد وضعیت HTTP 200 OK را به همراه داده های درخواستی برمی گرداند. اگر پارامتر فیلدها دارای خطا باشد یا در غیر این صورت نامعتبر باشد، سرور یک کد وضعیت HTTP 400 Bad Request را به همراه یک پیام خطایی مبنی بر مشکل انتخاب فیلدهای شما برمی گرداند. برای مثال، files.list(fields='files(id,capabilities,canAddChildren)') خطای "انتخاب فیلد نامعتبر canAddChildren" را نشان می دهد. پارامتر فیلدهای صحیح برای این مثال files.list(fields='files(id,capabilities/canAddChildren)') است.

برای تعیین فیلدهایی که می توانید با استفاده از پارامتر fields برگردانید، از صفحه مستندات منبعی که در حال جستجو هستید بازدید کنید. به عنوان مثال، برای اینکه ببینید چه فیلدهایی را می توانید برای یک فایل برگردانید، به مستندات منبع files مراجعه کنید.

قوانین فرمت پارامتر فیلد

فرمت مقدار پارامتر درخواست فیلدها بر اساس نحو XPath است. در زیر قوانین قالب بندی پارامتر fields آمده است. همه این قوانین از نمونه های مربوط به متد files.get() استفاده می کنند.

• از یک لیست جدا شده با کاما برای انتخاب چندین فیلد مانند 'name, mimeType' استفاده کنید.

• از a/b برای انتخاب فیلد b که در فیلد a تودرتو است، مانند 'capabilities/canDownload' استفاده کنید. برای اطلاعات بیشتر، واکشی فیلدهای یک منبع تودرتو را ببینید.

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

• برای برگرداندن تمام فیلدهای یک شی، از یک ستاره ( * ) به عنوان علامت عام در انتخاب فیلدها استفاده کنید. به عنوان مثال، 'permissions/permissionDetails/*' تمام فیلدهای جزئیات مجوز موجود را برای مجوز انتخاب می کند. توجه داشته باشید که استفاده از wildcard می تواند منجر به اثرات منفی عملکرد بر روی درخواست شود.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

فیلدهای یک منبع تودرتو را واکشی کنید

وقتی یک فیلد به منبع دیگری ارجاع می‌دهد، می‌توانید مشخص کنید که کدام فیلد از منبع تودرتو باید واکشی شود.

به عنوان مثال، برای بازیابی فیلد role (منبع تودرتو) منبع permissions ، از یکی از گزینه های زیر استفاده کنید:

• permissions.get() با fields=role .
• permissions.get() با fields=* برای نمایش تمام فیلدهای permissions .
• files.get() با fields=permissions(role) یا fields=permissions/role .
• files.get() با fields=permissions برای نمایش تمام فیلدهای permissions .
• changes.list() با fields=changes(file(permissions(role))) .

برای بازیابی چندین فیلد، از یک لیست جدا شده با کاما استفاده کنید. به عنوان مثال، files.list() با fields=files(id,name,createdTime,modifiedTime,size) .

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}

موضوعات مرتبط

• خطاها را برطرف کنید
• عیب یابی مشکلات احراز هویت و مجوز