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

หากต้องการแสดงฟิลด์ที่ตรงกับที่ต้องการและปรับปรุงประสิทธิภาพ ให้ใช้ 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)') จะแสดงข้อผิดพลาดว่า "Invalid field selection 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

  • หากต้องการแสดงผลช่องทั้งหมดในออบเจ็กต์ ให้ใช้เครื่องหมายดอกจัน (*) เป็นไวลด์การ์ดในการเลือกช่อง เช่น '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"
    }
  ]
}