แสดงเฉพาะบางช่อง

หากต้องการแสดงฟิลด์ที่ต้องการอย่างแน่นอนและปรับปรุงประสิทธิภาพ ให้ใช้fields พารามิเตอร์ระบบในการเรียกเมธอด

เอกสารนี้อธิบายวิธีใช้พารามิเตอร์ fields ใน Google ไดรฟ์

วิธีการทำงานของพารามิเตอร์ฟิลด์

พารามิเตอร์ 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/*' จะเลือก ฟิลด์รายละเอียดสิทธิ์ที่มีอยู่ทั้งหมดต่อสิทธิ์ โปรดทราบว่าการใช้ อักขระไวด์การ์ดอาจส่งผลเสียต่อประสิทธิภาพของคำขอ

คำขอ

ในตัวอย่างนี้ เราจะระบุพารามิเตอร์เส้นทางรหัสไฟล์และฟิลด์หลายรายการเป็นพารามิเตอร์การค้นหาในคำขอ การตอบกลับจะแสดงค่าฟิลด์สำหรับรหัสไฟล์

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"
    }
  ]
}