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

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

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

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

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

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

หากไม่ได้ระบุพารามิเตอร์ fields เซิร์ฟเวอร์จะแสดงผลชุดฟิลด์เริ่มต้นที่เฉพาะเจาะจงกับเมธอด เช่น เมธอด list ในทรัพจกร files จะแสดงผลเฉพาะฟิลด์ kind, id, name และ mimeType ส่วนเมธอด get ในทรัพยากร permissions จะแสดงผลชุดฟิลด์เริ่มต้น ที่แตกต่างกัน

สำหรับเมธอดทั้งหมดของทรัพยากร about, approvals, comments (ไม่รวม delete) และ replies (ไม่รวม delete) คุณ ต้อง ตั้งค่าพารามิเตอร์ fields เนื่องจากเมธอดเหล่านี้จะไม่แสดงผลชุดฟิลด์เริ่มต้น

หลังจากที่เซิร์ฟเวอร์ประมวลผลคำขอที่ถูกต้องซึ่งมีพารามิเตอร์ fields แล้ว เซิร์ฟเวอร์จะแสดงรหัสสถานะ HTTP 200 OK พร้อมกับข้อมูลที่ขอ หากพารามิเตอร์ fields มีข้อผิดพลาดหรือใช้ไม่ได้ เซิร์ฟเวอร์จะแสดงรหัสสถานะ HTTP 400 Bad Request พร้อมข้อความแสดงข้อผิดพลาดที่ระบุว่าการเลือกฟิลด์มีข้อผิดพลาด เช่น files.list(fields='files(id,capabilities,canAddChildren)') จะแสดงข้อผิดพลาด "การเลือกฟิลด์ canAddChildren ไม่ถูกต้อง" พารามิเตอร์ fields ที่ถูกต้องสำหรับตัวอย่างนี้คือ 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/*' จะเลือก ฟิลด์รายละเอียดสิทธิ์ทั้งหมดที่ใช้ได้ต่อสิทธิ์ โปรดทราบว่าการใช้ไวลด์การ์ดอาจส่งผลเสียต่อประสิทธิภาพของคำขอ

  • คุณเลือกองค์ประกอบแต่ละรายการของแผนที่ไม่ได้เมื่อคีย์มี สัญลักษณ์พิเศษ (เช่น เครื่องหมายทับ / หรือจุด .) เช่น การพยายามเลือกคีย์รูปแบบการส่งออกที่เฉพาะเจาะจงใน exportLinks โดยใช้ fields=exportLinks/application/pdf จะแสดงข้อผิดพลาด HTTP 400 Bad Request เนื่องจากตัวแยกวิเคราะห์เส้นทางตีความ / เป็นตัวคั่นพร็อพเพอร์ตี้ที่ซ้อนกัน หากต้องการดึงข้อมูลคู่คีย์-ค่าที่มีสัญลักษณ์พิเศษในคีย์ ให้ขอแผนที่ทั้งหมด (เช่น fields=exportLinks) และกรองผลลัพธ์ฝั่งไคลเอ็นต์

คำขอ

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

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)

หากต้องการระบุฟิลด์ที่ซ้อนกันภายในอาร์เรย์หรือออบเจ็กต์ที่ซ้อนกัน ให้ใช้วงเล็บที่ซ้อนกัน เช่น หากต้องการแสดงรายการไฟล์ที่มีรหัส ชื่อ และรายละเอียดเจ้าของที่ซ้อนกัน (ชื่อที่แสดงและอีเมล) พร้อมกับดึงข้อมูลโทเค็นหน้าถัดไปสำหรับการแบ่งหน้า ให้ใช้ files.list ที่มี fields=nextPageToken,files(id,name,owners(displayName,emailAddress))

คำขอ

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

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 Drive API จะมีเอกสารประกอบอยู่ที่ พารามิเตอร์ระบบ