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

این سند نحوه استفاده از پارامتر fields در Google Drive را توضیح می دهد.

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

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

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

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

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

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

پس از اینکه سرور یک درخواست معتبر را که شامل پارامتر 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 می تواند منجر به اثرات منفی عملکرد بر روی درخواست شود.

درخواست کنید

در این مثال، پارامتر مسیر ID فایل و چندین فیلد را به عنوان پارامتر پرس و جو در درخواست ارائه می کنیم. پاسخ مقادیر فیلد را برای شناسه فایل برمی گرداند.

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) .

درخواست کنید

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

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 Google Drive اعمال می شوند در پارامترهای سیستم مستند می شوند.

،

این سند نحوه استفاده از پارامتر fields در Google Drive را توضیح می دهد.

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

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

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

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

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

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

پس از اینکه سرور یک درخواست معتبر را که شامل پارامتر 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 می تواند منجر به اثرات منفی عملکرد بر روی درخواست شود.

درخواست کنید

در این مثال، پارامتر مسیر ID فایل و چندین فیلد را به عنوان پارامتر پرس و جو در درخواست ارائه می کنیم. پاسخ مقادیر فیلد را برای شناسه فایل برمی گرداند.

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) .

درخواست کنید

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

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 Google Drive اعمال می شوند در پارامترهای سیستم مستند می شوند.