เข้าถึงรายการสื่อที่แอปสร้างขึ้น

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

ขอบเขตการให้สิทธิ์ที่จําเป็น

การเข้าถึงรายการสื่อที่สร้างโดยแอปต้องใช้ขอบเขต photoslibrary.readonly.appcreateddata ดูข้อมูลเพิ่มเติมเกี่ยวกับขอบเขตได้ที่ขอบเขตการให้สิทธิ์

รายการสื่อ

mediaItem คือการนำเสนอสื่อ เช่น รูปภาพหรือวิดีโอที่อัปโหลดไปยังคลังภาพของ Google Photos ซึ่งเป็นออบเจ็กต์ระดับบนสุดและพร็อพเพอร์ตี้อาจแตกต่างกันไปตามประเภทสื่อที่อยู่เบื้องหลัง

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ mediaItem

พร็อพเพอร์ตี้
id รหัสแบบคงที่ถาวรที่ใช้ระบุออบเจ็กต์
description คำอธิบายรายการสื่อตามที่เห็นใน Google Photos
baseUrl ใช้เพื่อเข้าถึงไบต์ดิบ สำหรับข้อมูลเพิ่มเติม โปรดดูที่ URL หลัก
productUrl

ลิงก์ไปยังรูปภาพใน Google Photos นักพัฒนาแอปจะเปิดลิงก์นี้ไม่ได้ มีเพียงผู้ใช้เท่านั้นที่เปิดได้ URL ที่ชี้ไปยังรายการสื่อในไลบรารี หากดึงข้อมูล URL จากการค้นหาอัลบั้ม URL จะชี้ไปยังรายการภายในอัลบั้ม

mimeType ประเภทของรายการสื่อเพื่อช่วยระบุประเภทสื่อได้ง่ายๆ (เช่น image/jpg)
filename ชื่อไฟล์ของรายการสื่อที่แสดงต่อผู้ใช้ในแอป Google Photos (ในส่วนข้อมูลของรายการ)
mediaMetadata แตกต่างกันไปตามประเภทสื่อพื้นฐาน เช่น photo หรือ video หากต้องการลดเพย์โหลด คุณใช้ฟิลด์มาสก์ได้

รับรายการสื่อ

หากต้องการเรียกข้อมูลรายการสื่อ ให้เรียกใช้ mediaItems.get โดยใช้ mediaItemId คำขอจะแสดงรายการสื่อรายการเดียว

mediaItem มีพร็อพเพอร์ตี้ เช่น รหัส คำอธิบาย และ URL ข้อมูลเพิ่มเติมภายใน photo หรือ video จะอิงตามข้อมูลเมตาภายในไฟล์ อาจไม่มีที่พักบางแห่ง

หากรายการสื่อเป็นวิดีโอ ระบบจะต้องประมวลผลไฟล์วิดีโอก่อน mediaItem มีช่อง status ภายใน mediaMetadata ซึ่งอธิบายสถานะการประมวลผลของไฟล์วิดีโอ ไฟล์ที่อัปโหลดใหม่จะแสดง videoProcessingStatus ที่มีค่า PROCESSING ก่อน แล้วจึงเป็น READY สำหรับการใช้งาน baseUrl ของรายการสื่อวิดีโอจะใช้งานไม่ได้จนกว่าวิดีโอจะได้รับการประมวลผล

REST

คำขอ GET มีดังนี้

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

การตอบกลับสำหรับรายการสื่อรูปภาพจะมีลักษณะดังนี้ พร็อพเพอร์ตี้รูปภาพมีข้อมูลเมตาสำหรับรายการรูปภาพ

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "photo": {
       "cameraMake": "make-of-the-camera",
       "cameraModel": "model-of-the-camera",
       "focalLength": "focal-length-of-the-camera-lens",
       "apertureFNumber": "aperture-f-number-of-the-camera-lens",
       "isoEquivalent": "iso-of-the-camera",
       "exposureTime": "exposure-time-of-the-camera-aperture"
    }
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

การตอบสนองสำหรับรายการสื่อวิดีโอจะมีลักษณะดังนี้ พร็อพเพอร์ตี้วิดีโอมีข้อมูลเมตาสำหรับรายการวิดีโอ

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "video": {
     "cameraMake": "make-of-the-camera",
     "cameraModel": "model-of-the-camera",
     "fps": "frame-rate-of-the-video",
     "status": "READY"
    },
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

รับรายการสื่อหลายรายการ

หากต้องการเรียกรายการสื่อหลายรายการตามตัวระบุ ให้เรียก mediaItems.batchGet โดยใช้ mediaItemId

คำขอจะแสดงรายการ MediaItemResults ตามลําดับของตัวระบุรายการสื่อที่ระบุในคําขอ ผลลัพธ์แต่ละรายการจะมี MediaItem หรือ Status หากมีข้อผิดพลาด

จำนวนรายการสื่อสูงสุดที่คุณขอได้ในคอลเดียวคือ 50 รายการ รายการรายการสื่อต้องไม่มีตัวระบุที่ซ้ำกันและต้องไม่ว่างเปล่า

REST

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

GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

คำขอ GET จะแสดงผลลัพธ์ต่อไปนี้

{
  "mediaItemResults": [
    {
      "mediaItem": {
        "id": "media-item-id",
        ...
      }
    },
    {
      "mediaItem": {
        "id": "another-media-item-id",
        ...
      }
    },
    {
      "status": {
        "code": 3,
        "message": "Invalid media item ID."
      }
    }
  ]
}

URL ฐาน

URL พื้นฐานใน Google Photos API ให้สิทธิ์เข้าถึงไบต์ดิบของรายการสื่อ ซึ่งช่วยให้แอปของคุณดาวน์โหลดหรือแสดงรายการเหล่านั้นได้ URL เหล่านี้จะรวมอยู่ในคําตอบเมื่อแสดงรายการอัลบั้ม (Library API) หรือเข้าถึงรายการสื่อ (ทั้ง Library และ Picker API) อย่าลืมว่า URL พื้นฐานต้องมีพารามิเตอร์เพิ่มเติม เพื่อให้ทำงานได้อย่างถูกต้อง

สำหรับ Picker API

ออบเจ็กต์ PickedMediaItem.mediaFile ทั้งหมดมี baseUrl

URL พื้นฐานจะทำงานอยู่เป็นเวลา 60 นาที แต่อาจหมดอายุเร็วกว่านั้นหากผู้ใช้เพิกถอนสิทธิ์ของแอปผ่านการตั้งค่าบัญชี Google

สำหรับ Library API

URL ฐานจะยังคงใช้งานได้เป็นเวลา 60 นาที

URL พื้นฐานต่างๆ มีดังนี้

  • baseUrl: เข้าถึงรูปภาพ ภาพปกของวิดีโอ หรือดาวน์โหลดวิดีโอโดยตรง โดยไม่ผ่านแอป
  • coverPhotoBaseUrl: เข้าถึงรูปภาพปกของอัลบั้มโดยตรง
  • profilePictureBaseUrl: เข้าถึงรูปโปรไฟล์ของเจ้าของ mediaItem โดยตรง

URL ฐานของรูปภาพ

รายการตัวเลือกที่คุณใช้ได้กับ URL พื้นฐานของรูปภาพมีดังนี้

พารามิเตอร์
w h

คำอธิบาย

พารามิเตอร์ความกว้าง w และความสูง h

หากต้องการเข้าถึงรายการสื่อรูปภาพ เช่น รูปภาพหรือภาพขนาดย่อของวิดีโอ คุณต้องระบุขนาดที่คุณวางแผนจะแสดงในแอปพลิเคชัน (เพื่อให้ปรับขนาดรูปภาพเป็นขนาดเหล่านี้ได้ขณะที่ยังคงรักษาสัดส่วนภาพเดิมไว้) โดยให้ต่อท้าย URL พื้นฐานด้วยมิติข้อมูลที่ต้องการตามที่แสดงในตัวอย่าง

ตัวอย่างเช่น

base-url=wmax-width-hmax-height

ต่อไปนี้คือตัวอย่างการแสดงรายการสื่อที่มีความกว้างไม่เกิน 2048 พิกเซลและสูงไม่เกิน 1024 พิกเซล

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

คำอธิบาย

พารามิเตอร์ครอบตัด c

หากต้องการครอบตัดรูปภาพที่มีขนาดความกว้างและความสูงตรงตามที่คุณระบุไว้ ให้เชื่อมต่อ URL ฐานด้วยพารามิเตอร์ -c (ไม่บังคับ) พร้อมด้วยพารามิเตอร์ w และ h ที่จำเป็น

ขนาด (เป็นพิกเซล) ควรอยู่ในช่วง [1, 16383] หากความกว้างหรือความสูงของรูปภาพเกินขนาดที่ขอ ระบบจะปรับขนาดรูปภาพให้เล็กลงและครอบตัด (โดยคงสัดส่วนภาพไว้)

ตัวอย่างเช่น

base-url=wmax-width-hmax-height-c

ในตัวอย่างนี้ แอปพลิเคชันแสดงรายการสื่อที่มีความกว้าง 256 พิกเซลและสูง 256 พิกเซล เช่น ภาพขนาดย่อ

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

คำอธิบาย

พารามิเตอร์ d การดาวน์โหลด

หากต้องการดาวน์โหลดรูปภาพโดยเก็บข้อมูลเมตา Exif ทั้งหมดไว้ ยกเว้นข้อมูลเมตาตำแหน่ง ให้ต่อ URL ฐานกับพารามิเตอร์ d

ตัวอย่างเช่น

base-url=d

ในตัวอย่างนี้ แอปพลิเคชันจะดาวน์โหลดรูปภาพที่มีข้อมูลเมตาทั้งหมด ยกเว้นข้อมูลเมตาตำแหน่ง

https://lh3.googleusercontent.com/p/Az....XabC=d

URL หลักของวิดีโอ

รายการตัวเลือกที่คุณใช้ได้กับ URL พื้นฐานของวิดีโอมีดังนี้

พารามิเตอร์
dv

คำอธิบาย

หากต้องการเข้าถึงไบต์ของวิดีโอ mediaItem ให้ต่อbaseUrlเข้ากับพารามิเตอร์วิดีโอที่ดาวน์โหลด dv

พารามิเตอร์ dv จะขอวิดีโอต้นฉบับเวอร์ชันที่แปลงรูปแบบไว้แล้วและมีคุณภาพสูง พารามิเตอร์ ใช้ร่วมกับพารามิเตอร์ w และ h ไม่ได้

URL พื้นฐานสำหรับการดาวน์โหลดวิดีโออาจใช้เวลา 2-3 วินาทีในการแสดงผลไบต์

ก่อนใช้พารามิเตอร์นี้ ให้ตรวจสอบว่าช่อง mediaMetadata.status ของรายการสื่อเป็น READY มิเช่นนั้น คุณอาจพบข้อผิดพลาดหากรายการสื่อยังประมวลผลไม่เสร็จ

ตัวอย่างเช่น

base-url=dv

ตัวอย่างต่อไปนี้แสดงวิธีดาวน์โหลดจำนวนไบต์ของวิดีโอ

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c และ d

คำอธิบาย

หากต้องการเข้าถึงภาพปกของวิดีโอ ให้ใช้พารามิเตอร์ URL พื้นฐานของรูปภาพ

โดยค่าเริ่มต้น ภาพปกวิดีโอทั้งหมดจะมีปุ่มเล่นที่วางซ้อนอยู่ ดูพารามิเตอร์ -no เพื่อนำการวางซ้อนนี้ออก

ตัวอย่างเช่น

ดูตัวอย่างได้ที่ตาราง URL ฐานของรูปภาพ
no

คำอธิบาย

พารามิเตอร์ no สำหรับนำการวางซ้อนภาพปกออก

หากต้องการเรียกข้อมูลภาพปกของวิดีโอโดยไม่มีปุ่มเล่นที่วางซ้อน ให้ต่อ URL พื้นฐานกับพารามิเตอร์ no

ต้องใช้พารามิเตอร์ no กับพารามิเตอร์ URL พื้นฐานของรูปภาพอย่างน้อย 1 รายการ

ตัวอย่างเช่น

base-url=wmax-width-hmax-height-no

ตัวอย่างต่อไปนี้แสดงภาพขนาดย่อของวิดีโอที่มีความกว้าง 1280 พิกเซลและสูง 720 พิกเซลโดยไม่มีปุ่มเล่นวางซ้อน

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URL ฐานของรูปภาพเคลื่อนไหว

รูปภาพเคลื่อนไหวมีองค์ประกอบทั้งรูปภาพและวิดีโอ คุณสามารถใช้พารามิเตอร์จาก URL ฐานรูปภาพหรือ URL ฐานวิดีโอสำหรับคำขอภาพเคลื่อนไหว baseUrl

พารามิเตอร์
dv

คำอธิบาย

หากต้องการเรียกข้อมูลองค์ประกอบวิดีโอของรายการสื่อรูปภาพเคลื่อนไหว ให้ใช้พารามิเตอร์ dv เช่นเดียวกับการดาวน์โหลดจาก URL พื้นฐานของวิดีโอ
w, h, c และ d

คำอธิบาย

หากต้องการเรียกข้อมูลองค์ประกอบรูปภาพของรายการสื่อรูปภาพเคลื่อนไหว ให้ใช้รูปแบบสำหรับ URL ฐานรูปภาพ