ขอบเขตการให้สิทธิ์ที่จำเป็น
Google Photos Library API มีขอบเขตหลายขอบเขตที่ใช้ในการเข้าถึงรายการสื่อและอัลบั้ม รายการสื่อที่แสดงผลจากการเรียกต่างๆ จะแตกต่างกันไปตามขอบเขตที่นักพัฒนาซอฟต์แวร์ได้ขอ
ขอบเขต photoslibrary.readonly
อนุญาตให้เข้าถึงรายการสื่อทั้งหมดในไลบรารีของผู้ใช้ ขอบเขต photoslibrary.readonly.appcreateddata
จะอนุญาตการเข้าถึงเฉพาะรายการสื่อที่แอปสร้างขึ้น ดูข้อมูลเพิ่มเติมได้ที่ขอบเขตการให้สิทธิ์
ภาพรวม
การใช้งาน API ที่สำคัญคือเพื่อแสดงรายการสื่อที่ผู้ใช้สำรองข้อมูลไว้ใน Google Photos รายการในอัลบั้มใดอัลบั้มหนึ่งหรือจากห้องสมุดทั้งหมดของผู้ใช้ (มุมมองเริ่มต้นในแอป Google Photos) สามารถแสดงในรายการได้
คุณใช้ตัวกรองเพื่อเลือกรูปภาพที่ตรงกับวันที่ หมวดหมู่เนื้อหา หรือประเภทสื่อที่ระบุได้เมื่อแสดงรายการจากคลังภาพของผู้ใช้ ฟีเจอร์นี้จะใช้ไม่ได้เมื่อคุณแสดงรายการจากอัลบั้ม
การแสดงรายการไลบรารีและเนื้อหาอัลบั้มจะแสดงรายการสื่อ
ข้อมูลเสริมที่เป็นส่วนหนึ่งของอัลบั้ม
จะไม่รวมอยู่ในนี้ รายการสื่ออธิบายรูปภาพ วิดีโอ หรือสื่ออื่นๆ mediaItem
ประกอบด้วยลิงก์โดยตรงไปยังรายการดังกล่าว ลิงก์ไปยังรายการใน Google Photos และข้อมูลเมตาอื่นๆ ที่เกี่ยวข้อง ดูข้อมูลเพิ่มเติมได้ที่เข้าถึงรายการสื่อและmediaItems
รายชื่ออัลบั้ม
คุณเรียกดูรายการอัลบั้มของผู้ใช้ได้โดยใช้ albums.list
REST
ตัวอย่างคำขอมีดังนี้
GET https://photoslibrary.googleapis.com/v1/albums
คำขอจะแสดงผลลัพธ์ต่อไปนี้:
{ "albums": [ { "id": "album-id", "title": "album-title", "productUrl": "album-product-url", "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly", "coverPhotoMediaItemId": "album-cover-media-item-id", "isWriteable": "whether-you-can-write-to-this-album", "mediaItemsCount": "number-of-media-items-in-album" }, ... ], "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all albums in the user's library // Iterate over all the albums in this list // Pagination is handled automatically ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(); for (Album album : response.iterateAll()) { // Get some properties of an album String id = album.getId(); String title = album.getTitle(); String productUrl = album.getProductUrl(); String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl(); // The cover photo media item id field may be empty String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId(); boolean isWritable = album.getIsWriteable(); long mediaItemsCount = album.getMediaItemsCount(); } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums in the user's library // Iterate over all the albums in this list // Pagination is handled automatically $response = $photosLibraryClient->listAlbums(); foreach ($response->iterateAllElements() as $album) { // Get some properties of an album $albumId = $album->getId(); $title = $album->getTitle(); $productUrl = $album->getProductUrl(); $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl(); // The cover photo media item id field may be empty $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId(); $isWriteable = $album->getIsWriteable(); $totalMediaItems = $album->getTotalMediaItems(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
อัลบั้มที่ส่งคืนแต่ละอัลบั้มจะมีรหัสที่สามารถใช้เรียกดูเนื้อหาของอัลบั้มนั้นได้ตามที่แสดงในการแสดงเนื้อหาอัลบั้ม นอกจากนี้ยังรวมถึงชื่อและจำนวนรายการสื่อที่อยู่ในเนื้อหาด้วย
productUrl
จะชี้ไปยังอัลบั้มใน Google Photos ที่ผู้ใช้เปิดได้
coverPhotoMediaItemId
มีรหัสรายการสื่อที่แสดงรูปภาพปกของอัลบั้มนี้ หากต้องการเข้าถึงภาพหน้าปกนี้ ให้ใช้ coverPhotoBaseUrl
คุณไม่ควรใช้ coverPhotoBaseUrl
โดยตรงโดยไม่ได้ระบุพารามิเตอร์เพิ่มเติม
อัลบั้มที่สร้างในบัญชีของผู้ใช้หรือเพิ่มลงในบัญชีของผู้ใช้และที่แอปของคุณแชร์จะมีพร็อพเพอร์ตี้ shareInfo
เพิ่มเติม
โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อแชร์สื่อ
อัลบั้มยังอาจมีแฟล็ก isWriteable
เพื่อระบุว่าคุณสามารถสร้างรายการสื่อในอัลบั้มได้หรือไม่ แฟล็กนี้จะมีค่าเริ่มต้นเป็น false
หากไม่แสดงผล โดยขึ้นอยู่กับการเข้าถึงที่ให้กับแอปพลิเคชันของคุณ ซึ่งรวมถึงสิ่งต่อไปนี้
- ผู้ที่สร้างอัลบั้ม
- ว่ามีการแชร์หรือไม่
- ขอบเขตที่ผู้ใช้อนุมัติ
ธงนี้อาจเปลี่ยนแปลงได้หากเกณฑ์เหล่านี้มีการเปลี่ยนแปลง ดูรายละเอียดเพิ่มเติมได้ที่สร้างอัลบั้ม คําตอบจะมี nextPageToken
ด้วย ดูข้อมูลเพิ่มเติมได้ที่การใส่เลขหน้า
การตอบกลับสำหรับอัลบั้มที่ว่างเปล่าจะแตกต่างกันไป โดย mediaItemsCount
และ coverPhotoMediaItemId
จะตั้งค่าไว้เป็น 0 โดยค่าเริ่มต้น และจะไม่อยู่ในการตอบกลับของ REST และโปรดทราบว่า coverPhotoBaseUrl
ชี้ไปยังรูปภาพตัวยึดตำแหน่งเริ่มต้น
เนื้อหาในไลบรารีรายชื่อ
คุณสามารถแสดงรายการสื่อทั้งหมดจากคลังภาพ Google Photos ของผู้ใช้ แต่ไม่รวมรายการที่เก็บถาวรและถูกลบ คุณแสดงรายการสื่อตามเนื้อหา วันที่ และพร็อพเพอร์ตี้อื่นๆ ได้โดยการใช้ตัวกรอง หากผู้ใช้ไม่ได้เพิ่มรายการที่อยู่ในแท็บการแชร์ของ Google Photos ลงในคลังภาพ รายการดังกล่าวจะไม่รวมอยู่ในรายการนี้
หากต้องการเรียกรายการสื่อ ให้เรียก mediaItems.list
REST
ตัวอย่างคำขอมีดังนี้
GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
}
คำขอ GET แสดงการตอบกลับต่อไปนี้
{ "mediaItems": [ ... ], "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all media items in the user's library // Iterate over all the retrieved media items // Pagination is handled automatically ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems(); for (MediaItem item : response.iterateAll()) { // Get some properties of a media item String id = item.getId(); String description = item.getDescription(); String mimeType = item.getMimeType(); String productUrl = item.getProductUrl(); String filename = item.getFilename(); } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all media items in the user's library // Iterate over all the retrieved media items // Pagination is handled automatically $response = $photosLibraryClient->listMediaItems(); foreach ($response->iterateAllElements() as $item) { // Get some properties of a media item /* @var $item \Google\Photos\Library\V1\MediaItem */ $id = $item->getId(); $description = $item->getDescription(); $mimeType = $item->getMimeType(); $productUrl = $item->getProductUrl(); $filename = $item->getFilename(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
คําตอบจะประกอบด้วยรายการสื่อที่เรียงจากใหม่สุดไปล่าสุด
ดูข้อมูลเพิ่มเติมได้ที่ mediaItems
และยังมี nextPageToken
ซึ่งอธิบายไว้อย่างละเอียดในการใส่เลขหน้า
แสดงเนื้อหาในอัลบั้ม
หากต้องการแสดงรายการสื่อทั้งหมดในอัลบั้ม ให้เพิ่มช่อง albumId
ในคำขอค้นหา ดูข้อมูลเพิ่มเติมเกี่ยวกับ albumId
ดูการแสดงอัลบั้มและการแสดงอัลบั้มที่แชร์ หาก albumId
ไม่ถูกต้อง ระบบจะแสดงข้อผิดพลาด Bad Request
ถ้ารหัสถูกต้องแต่ไม่มีอัลบั้มสำหรับผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว ระบบจะแสดงข้อผิดพลาด Not Found
ดูรายละเอียดเพิ่มเติมเกี่ยวกับการจัดการข้อผิดพลาดได้ในเคล็ดลับด้านประสิทธิภาพและแนวทางปฏิบัติแนะนำ
REST
ตัวอย่างคำขอมีดังนี้
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"albumId": "album-id"
}
คำขอ POST จะแสดงผลการตอบกลับต่อไปนี้:
{ "mediaItems": [ ... ], "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all media items in an album // Provide the ID of the album as a parameter in the searchMediaItems call // Iterate over all the retrieved media items SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId); for (MediaItem item : response.iterateAll()) { // ... } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all media items in an album // Provide the ID of the album as a parameter in the searchMediaItems call // Iterate over all the retrieved media items $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]); foreach ($response->iterateAllElements() as $item) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
คําตอบมี nextPageToken
และลิสต์สื่อ รายการสื่อจะแสดงตามลำดับในอัลบั้ม ซึ่งต่างจากตอนที่แสดงเนื้อหาในคลัง ดูรายละเอียดเพิ่มเติมได้ที่
mediaItems
และการใส่เลขหน้า ผู้ใช้จะแก้ไขลำดับได้ในอินเทอร์เฟซของ Google Photos
หากตั้งค่า albumId
แล้ว คุณจะไม่สามารถใช้ตัวกรองเมื่อแสดงเนื้อหาของอัลบั้มได้
มิฉะนั้นจะเกิดข้อผิดพลาด Bad Request
แสดงรายการอัลบั้มที่แชร์
คุณสามารถเรียกดูรายการอัลบั้มทั้งหมดที่ผู้ใช้แชร์หรือที่แชร์กับผู้ใช้ได้ ซึ่งคล้ายกับแท็บการแชร์ใน แอป Google Photos
อัลบั้มที่แชร์ที่ผู้ใช้เพิ่มไว้ในคลังภาพ Google Photos ยังจะปรากฏในการโทรแสดงรายการอัลบั้มด้วย ดำเนินการเรียกรายการต่อไปนี้เพื่อแสดงอัลบั้มที่แชร์ผ่าน Library API:
REST
ตัวอย่างคำขอมีดังนี้
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
คำขอจะแสดงผลลัพธ์ต่อไปนี้:
{ "sharedAlbums": [...] "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all albums that have been shared by the user // Iterate over all the albums in this list // Pagination is handled automatically ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums(); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums that have been shared by the user // Iterate over all the albums in this list // Pagination is handled automatically $response = $photosLibraryClient->listSharedAlbums(); foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
รายการอัลบั้มจะรวมอยู่ใน sharedAlbums
ดูข้อมูลเพิ่มเติมได้ที่การแสดงอัลบั้ม คำตอบยังมี nextPageToken
ด้วย
ดูข้อมูลเพิ่มเติมได้ที่การใส่เลขหน้า
อัลบั้มที่แอปของคุณสร้างและแชร์จะมีพร็อพเพอร์ตี้ shareInfo
เพิ่มเติม ดูรายละเอียดเพิ่มเติมได้ที่แชร์สื่อ
อัลบั้มที่สร้างโดยแอปรายชื่อ
คุณสามารถแสดงรายการอัลบั้มที่แอปสร้างขึ้นโดยตั้งค่า excludeNonAppCreatedData
เป็น true
ในการเรียกต่อไปนี้
REST
นี่คือคำขอ GET ที่แสดงรายการอัลบั้มทั้งหมดจากคลังภาพ Google Photos ของผู้ใช้ที่แอปของคุณสร้างขึ้นเท่านั้น
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
นี่คือคำขอ GET ที่แสดงรายการอัลบั้มที่แชร์ทั้งหมดจากคลังภาพ Google Photos ของผู้ใช้ที่แอปของคุณสร้างขึ้นเท่านั้น
GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Java
try { // Make a request to list all albums that have been created by your app boolean excludeNonAppCreatedData = true; // Iterate over all the albums in this list // Pagination is handled automatically ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error } try { // Make a request to list all shared albums that have been created by your app boolean excludeNonAppCreatedData = true; // Iterate over all the albums in this list // Pagination is handled automatically ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums that have been created by your app $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]); // Iterate over all the albums in this list // Pagination is handled automatically foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error } try { // Make a request to list all shared albums that have been created by your app $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]); // Iterate over all the albums in this list // Pagination is handled automatically foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
การใส่เลขหน้าสำหรับ REST
ในการปรับปรุงประสิทธิภาพ วิธีการที่แสดงผลการค้นหาจำนวนมาก (เช่น วิธีการแบบลิสต์) อาจใส่เลขหน้าให้คำตอบ จำนวนผลลัพธ์สูงสุดในแต่ละหน้ากำหนดโดยพารามิเตอร์ pageSize
สำหรับการเรียกไปยัง mediaItems:search
และ mediaItems:list
ขนาดหน้าเว็บเริ่มต้นคือ 25 รายการ เราแนะนำขนาดหน้าเว็บนี้เพราะจะทำให้เกิดความสมดุลระหว่างขนาดของการตอบกลับและอัตราการส่งโฆษณา ขนาดสูงสุดของหน้าเว็บสำหรับคำขอการค้นหาและรายการสื่อคือ 100 รายการ
ขนาดหน้าเริ่มต้นและที่แนะนำเมื่อแสดงอัลบั้มคือ 20 อัลบั้ม โดยมีได้สูงสุด 50 อัลบั้ม
เมื่อผลลัพธ์มีจำนวนมากกว่าขนาดหน้าเว็บ การตอบกลับจะมี nextPageToken
ซึ่งบอกแอปพลิเคชันว่ามีผลลัพธ์เพิ่มเติมที่ให้ดึงจากเซิร์ฟเวอร์
ตัวอย่าง
คุณต้องเพิ่ม nextPageToken
ต่อท้ายคำขอในพารามิเตอร์ pageToken
ดังที่แสดงในตัวอย่างต่อไปนี้ ระบุ pageToken
พร้อมกับพารามิเตอร์อื่นๆ ที่จำเป็นสำหรับการดำเนินการ ทั้งในเนื้อหาของคำขอหรือเป็นพารามิเตอร์การค้นหา
คำขอ #1
{ "pageSize": "5", "filters": { … } }
คำตอบที่ 1
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
คำขอ #2
{ "pageSize": "5", "filters": { … }, "pageToken": "page-token" }
คำตอบที่ 2
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
ใช้รูปแบบนี้ต่อไปจนกว่าจะไม่มีออบเจ็กต์ nextPageToken
อีก
nextPageToken
ใช้ได้กับคำขอเดียวกันเท่านั้น หากมีการเปลี่ยนแปลงพารามิเตอร์ คุณไม่ควรใช้ nextPageToken
ที่ใช้ก่อนหน้านี้ในคำขอเดียวกัน