เอกสารนี้ครอบคลุมข้อควรพิจารณาที่สำคัญสำหรับการตั้งชื่อไฟล์และการทำงานกับข้อมูลเมตา เช่น ข้อความที่จัดทำดัชนีได้และภาพปก หากต้องการแทรกและเรียกข้อมูลไฟล์ โปรดดูแหล่งข้อมูล files
ภาพรวมของข้อมูลเมตา
ใน Google Drive API files ทรัพยากรจะแสดงข้อมูลเมตา ซึ่งแตกต่างจาก API ที่ข้อมูลเมตาเป็นออบเจ็กต์ย่อย Drive API จะถือว่าทั้งfilesเป็นข้อมูลเมตา คุณเข้าถึงข้อมูลเมตาได้โดยตรงผ่านเมธอด
get หรือ list ในทรัพยากร files
โดยค่าเริ่มต้น เมธอด get และ list จะแสดงผลเฉพาะชุดฟิลด์บางส่วน หากต้องการ
ดึงข้อมูลที่เฉพาะเจาะจง คุณต้องกำหนดfields พารามิเตอร์
ระบบในคำขอ หากไม่ระบุ เซิร์ฟเวอร์จะแสดงผลฟิลด์ย่อยเริ่มต้นที่เจาะจง
สำหรับเมธอด เช่น เมธอด list จะแสดงเฉพาะฟิลด์ kind, id,
name, mimeType และ resourceKey สำหรับแต่ละไฟล์ หากต้องการแสดงช่องอื่น ให้ดูแสดงช่องที่เฉพาะเจาะจง
นอกจากนี้ การมองเห็นข้อมูลเมตาจะขึ้นอยู่กับบทบาทของผู้ใช้ในไฟล์ด้วย ทรัพยากร
permissions ไม่ได้กำหนดการดำเนินการที่ผู้ใช้ได้รับอนุญาตให้ทำกับไฟล์หรือโฟลเดอร์
แต่filesทรัพยากร
จะมีคอลเล็กชันของช่องบูลีน
capabilities Google ไดรฟ์ API จะดึงข้อมูลcapabilitiesเหล่านี้จากทรัพยากร permissions ที่เชื่อมโยงกับไฟล์หรือโฟลเดอร์ ดูข้อมูลเพิ่มเติมได้ที่ทำความเข้าใจความสามารถของไฟล์
Drive API มีขอบเขตข้อมูลเมตาที่จำกัด 2 รายการ ได้แก่ drive.metadata
และ drive.metadata.readonly drive.metadata ช่วยให้คุณดูและจัดการข้อมูลเมตาของไฟล์ได้ ส่วน drive.metadata.readonly เป็นแบบอ่านอย่างเดียว ทั้ง 2 อย่าง
ห้ามไม่ให้เข้าถึงเนื้อหาไฟล์อย่างเคร่งครัด ดูข้อมูลเพิ่มเติมได้ที่เลือก
ขอบเขต Google Drive API
สุดท้ายนี้ โปรดตรวจสอบตรรกะเกี่ยวกับสิทธิ์และขอบเขตเสมอ ตัวอย่างเช่น
ผู้ใช้อาจเป็นเจ้าของไฟล์ที่มีสิทธิ์เต็ม แต่ Drive API จะ
บล็อกความพยายามในการแก้ไขหรือดาวน์โหลดไฟล์หากแอปของคุณมีเพียงขอบเขต drive.metadata.readonly
ระบุชื่อและนามสกุลไฟล์
แอปควรกำหนดนามสกุลไฟล์ในพร็อพเพอร์ตี้
name) เมื่อแทรก
ไฟล์ด้วย Google Drive API เช่น การดำเนินการเพื่อแทรกไฟล์ JPEG
ควรระบุค่า เช่น "name": "cat.jpg" ในข้อมูลเมตา
การตอบกลับ GET ในภายหลังอาจมีพร็อพเพอร์ตี้ fileExtension แบบอ่านอย่างเดียวซึ่งมีส่วนขยายที่ระบุไว้เดิมในพร็อพเพอร์ตี้ name เมื่อผู้ใช้ Google ไดรฟ์
ขอดาวน์โหลดไฟล์ หรือเมื่อมีการดาวน์โหลดไฟล์ผ่าน
ไคลเอ็นต์การซิงค์ ไดรฟ์จะสร้างชื่อไฟล์แบบเต็ม (พร้อมนามสกุล) ตามชื่อ
ในกรณีที่ไม่มีนามสกุล Drive
จะพยายามระบุนามสกุลตามประเภท MIME ของไฟล์
บันทึกข้อความที่จัดทำดัชนีได้
ไดรฟ์จะจัดทำดัชนีเอกสารสำหรับการค้นหาโดยอัตโนมัติเมื่อ
รู้จักประเภทไฟล์ ซึ่งรวมถึงเอกสารข้อความ, PDF, รูปภาพที่มีข้อความ และ
ประเภทอื่นๆ ที่พบบ่อย หากแอปบันทึกไฟล์ประเภทอื่นๆ (เช่น ภาพวาด วิดีโอ และทางลัด) คุณจะปรับปรุงการค้นพบได้โดยระบุข้อความที่ทำดัชนีได้ในฟิลด์ contentHints.indexableText ของไฟล์
ระบบจะจัดทำดัชนีข้อความที่จัดทำดัชนีได้เป็น HTML หากคุณบันทึกสตริงข้อความที่จัดทำดัชนีได้
<section attribute="value1">Here's some text</section> ระบบจะจัดทำดัชนี "Here's some
text" แต่จะไม่จัดทำดัชนี "value1" ด้วยเหตุนี้ การบันทึก XML เป็นข้อความที่จัดทำดัชนีได้จึงมีประโยชน์น้อยกว่าการบันทึก HTML
เมื่อระบุ indexableText โปรดคำนึงถึงสิ่งต่อไปนี้ด้วย
contentHints.indexableTextมีขนาดไม่เกิน 128 KB- บันทึกคำและแนวคิดสำคัญที่คุณคาดว่าผู้ใช้จะค้นหา
- อย่าพยายามจัดเรียงข้อความตามลำดับความสำคัญเนื่องจากเครื่องมือจัดทำดัชนีจะดำเนินการดังกล่าว อย่างมีประสิทธิภาพให้คุณ
- แอปพลิเคชันควรอัปเดตข้อความที่จัดทำดัชนีได้ทุกครั้งที่บันทึก
- ตรวจสอบว่าข้อความเกี่ยวข้องกับเนื้อหาหรือข้อมูลเมตาของไฟล์
แม้ว่าข้อสุดท้ายนี้อาจดูเหมือนเป็นเรื่องที่ชัดเจนอยู่แล้ว แต่ก็เป็นเรื่องสำคัญ ไม่ควร เพิ่มคำที่มักมีการค้นหาเพื่อบังคับให้ไฟล์ปรากฏในผลการค้นหา ซึ่งอาจสร้างความหงุดหงิดให้ผู้ใช้ และอาจกระตุ้นให้ผู้ใช้ลบไฟล์
อัปโหลดภาพปก
ไดรฟ์จะสร้างภาพขนาดย่อสำหรับไฟล์ประเภททั่วไปหลายประเภทโดยอัตโนมัติ เช่น Google เอกสาร, ชีต และสไลด์ ภาพขนาดย่อช่วยให้ผู้ใช้ระบุไฟล์ในไดรฟ์ได้ดียิ่งขึ้น
สำหรับประเภทไฟล์ที่ไดรฟ์สร้างภาพขนาดย่อมาตรฐานไม่ได้ คุณสามารถระบุรูปภาพภาพขนาดย่อที่แอปพลิเคชันของคุณสร้างขึ้นได้ ในระหว่างการสร้างหรืออัปเดตไฟล์ ให้อัปโหลดภาพปกโดยตั้งค่าฟิลด์ contentHints.thumbnail ในทรัพยากร files
ดังนี้
- ตั้งค่าฟิลด์
contentHints.thumbnail.imageเป็น URL และชื่อไฟล์ที่ปลอดภัย รูปภาพที่เข้ารหัส Base64 (ดูส่วน RFC 4648 5) - ตั้งค่าฟิลด์
contentHints.thumbnail.mimeTypeเป็นประเภท MIME ที่เหมาะสม สำหรับภาพขนาดย่อ
หากไดรฟ์สร้างภาพขนาดย่อจากไฟล์ได้ ไดรฟ์จะใช้ภาพขนาดย่อที่สร้างขึ้นโดยอัตโนมัติและไม่สนใจภาพขนาดย่อที่คุณอาจอัปโหลด หากสร้างภาพปกไม่ได้ ระบบจะใช้ภาพปกที่คุณระบุ
ภาพปกควรเป็นไปตามกฎต่อไปนี้
- อัปโหลดได้ในรูปแบบ PNG, GIF หรือ JPG
- ความกว้างที่แนะนำคือ 1600 พิกเซล
- ความกว้างขั้นต่ำคือ 220 พิกเซล
- ขนาดของไฟล์ต้องไม่เกิน 2 MB
- แอปพลิเคชันของคุณควรจะอัปเดตข้อมูลเหล่านี้ทุกครั้งที่บันทึก
ดูข้อมูลเพิ่มเติมได้ที่แหล่งข้อมูล files
ดึงข้อมูลภาพปก
คุณสามารถดึงข้อมูลเมตา รวมถึงภาพขนาดย่อของไฟล์ในไดรฟ์ได้
ข้อมูลภาพปกจะอยู่ในฟิลด์
thumbnailLink ของ
ทรัพยากร files
แสดงผลภาพปกที่เฉพาะเจาะจง
ตัวอย่างโค้ดต่อไปนี้แสดงคำขอเมธอด get
ที่มีหลายฟิลด์เป็นพารามิเตอร์การค้นหาเพื่อแสดงผลข้อมูลเมตา thumbnailLink
สำหรับไฟล์ที่เฉพาะเจาะจง ดูข้อมูลเพิ่มเติมได้ที่แสดงผลฟิลด์ที่เฉพาะเจาะจง
สำหรับไฟล์
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
แทนที่ FILE_ID ด้วย fileId ของไฟล์ที่ต้องการค้นหา
หากมี URL ที่มีอายุสั้นไปยังภาพปกของไฟล์จะแสดงในคำขอ
โดยปกติแล้วลิงก์จะใช้งานได้หลายชั่วโมง ระบบจะป้อนข้อมูลในช่องนี้เมื่อ
แอปที่ขอเข้าถึงเนื้อหาของไฟล์ได้เท่านั้น หากไม่ได้แชร์ไฟล์แบบสาธารณะ คุณต้องดึงข้อมูล URL ที่แสดงใน thumbnailLink โดยใช้คำขอที่ต้องใช้ข้อมูลเข้าสู่ระบบ
แสดงรายการภาพขนาดย่อ
ตัวอย่างโค้ดต่อไปนี้แสดงคำขอเมธอด list
ที่มีหลายช่องเป็นพารามิเตอร์การค้นหาเพื่อแสดงผลข้อมูลเมตา thumbnailLink
สำหรับรายการไฟล์ ดูข้อมูลเพิ่มเติมได้ที่ค้นหาไฟล์และโฟลเดอร์
GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)
หากต้องการจำกัดผลการค้นหาให้เป็นประเภทไฟล์ที่เฉพาะเจาะจง ให้ใช้สตริงการค้นหาเพื่อตั้งค่าประเภท MIME ตัวอย่างเช่น ตัวอย่างโค้ดต่อไปนี้แสดงวิธีจำกัดรายการให้แสดงเฉพาะไฟล์ Google ชีต ดูข้อมูลเพิ่มเติมเกี่ยวกับประเภท MIME ได้ที่ ประเภท MIME ที่รองรับใน Google Workspace และ Google ไดรฟ์
GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)