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

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

พารามิเตอร์ fields ใช้ FieldMask ในการกรองการตอบกลับ มาสก์ช่องใช้เพื่อระบุชุดย่อยของช่องที่คำขอควรแสดงผล การใช้มาสก์ฟิลด์เป็นแนวทางปฏิบัติในการออกแบบที่ดีเพื่อให้แน่ใจว่าคุณไม่ได้ขอข้อมูลที่ไม่จำเป็น ซึ่งจะช่วยหลีกเลี่ยงเวลาในการประมวลผลที่ไม่จำเป็น

โดยค่าเริ่มต้น เซิร์ฟเวอร์จะแสดงชุดช่องเฉพาะสำหรับทรัพยากรที่ค้นหา เช่น เมธอด get() ในแหล่งข้อมูล files อาจแสดงผลแค่ id, name และ mimeType เท่านั้น เมธอด get() ในทรัพยากร permissions แสดงผลชุดช่องเริ่มต้นที่ต่างออกไป

หลังจากเซิร์ฟเวอร์ประมวลผลคําขอที่ถูกต้องซึ่งมีพารามิเตอร์ fields แล้ว ระบบจะแสดงรหัสสถานะ HTTP 200 OK พร้อมกับข้อมูลที่ขอ หากพารามิเตอร์ HTTP 400 Bad Request มีข้อผิดพลาดหรือไม่ถูกต้อง เซิร์ฟเวอร์จะแสดงรหัสสถานะ 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"
    }
  ]
}