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

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

به‌طور پیش‌فرض، سرور مجموعه‌ای از فیلدها را به منبعی که مورد پرسش قرار می‌گیرد، باز می‌فرستد. برای مثال، متد files.get ممکن است فقط id ، name و mimeType را برای منبع files برگرداند. متد permissions.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/*' تمام فیلدهای جزئیات مجوز موجود را برای مجوز انتخاب می کند. توجه داشته باشید که استفاده از این حروف عام می تواند منجر به تاثیرات منفی عملکرد بر روی درخواست شود.

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 یا fields=* .
• files.get با fields=permissions(role) یا fields=permissions/role .
• files.get با fields=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"
    }
  ]
}