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

این سند نحوه استفاده از پارامتر fields در گوگل درایو را توضیح می‌دهد.

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

برای اطلاعات در مورد سایر پارامترهای سیستم که در مورد Drive API اعمال می‌شوند، به پارامترهای سیستم جایگزین مراجعه کنید.

نحوه عملکرد پارامتر fields

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

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

برای همه متدهای منابع about ، comments (به جز delete ) و replies (به جز delete ) باید پارامتر fields را تنظیم کنید. این متدها مجموعه پیش‌فرضی از فیلدها را برنمی‌گردانند.

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

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

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

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

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

  • a/b برای انتخاب فیلد b که درون فیلد a قرار دارد، مانند 'capabilities/canDownload' ، استفاده کنید. برای اطلاعات بیشتر، به Fetch the fields of a nested resource مراجعه کنید.

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

  • برای برگرداندن تمام فیلدهای یک شیء، از علامت ستاره ( * ) به عنوان wildcard در انتخاب فیلدها استفاده کنید. برای مثال، '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"
    }
  ]
}

پارامترهای سیستم جایگزین

پارامترهای پرس‌وجویی که برای تمام عملیات API گوگل درایو اعمال می‌شوند، در System Parameters مستند شده‌اند.