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

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

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

ดูข้อมูลเกี่ยวกับพารามิเตอร์ระบบอื่นๆ ที่ใช้กับ Drive API ได้ที่พารามิเตอร์ระบบทางเลือก

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

พารามิเตอร์ 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เอกสารประกอบของทรัพยากร ดูคำค้นหาที่เฉพาะเจาะจงกับไฟล์เพิ่มเติมได้ที่คำและโอเปอเรเตอร์ของคำค้นหา

กฎรูปแบบพารามิเตอร์ฟิลด์

รูปแบบของค่าพารามิเตอร์คำขอฟิลด์อิงตามไวยากรณ์ 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"
    }
  ]
}

พารามิเตอร์ระบบอื่น

พารามิเตอร์การค้นหาที่มีผลกับการดำเนินการทั้งหมดของ Google ไดรฟ์ API จะมีการบันทึกไว้ที่ พารามิเตอร์ของระบบ

หัวข้อที่เกี่ยวข้อง

• แก้ไขข้อผิดพลาด
• แก้ปัญหาการตรวจสอบสิทธิ์และการให้สิทธิ์
• ปรับปรุงประสิทธิภาพ