Fotoğraf kitaplığının veya albümünün içeriğini listelemek için çağrı yaptıktan sonra uygulamanız, döndürülen medya öğelerini depolamak yerine medya öğelerinin kimliklerini depolamalıdır. Bunun nedeni, medya öğelerinin içeriğinin değişebilmesi ve belirli bir süre sonra yanıta dahil edilen URL'lerin süresinin dolmasıdır. Medya öğesi kimliği, kullanıcının kitaplığındaki bir medya öğesini (ör. fotoğraf veya video) benzersiz şekilde tanımlar.
Uygulamanızın, bir kullanıcının fotoğrafını veya videosunu uzun süre önbelleğe almaması gerektiğini unutmayın. Ancak kullanım alanınıza bağlı olarak, medya öğesi kimliğini gerektiği kadar saklayabilir veya önbelleğe alabilirsiniz. Ayrıca kullanıcı verilerine erişimin, gizlilikle ilgili yükümlülüklere tabi olduğunu unutmayın.
Gerekli yetkilendirme kapsamları
Medya öğelerine erişmek için uygulamanızın aşağıdaki yetkilendirme kapsamlarından en az birini istemesi gerekir. Yanıtta döndürülen medya öğelerine erişim, istediğiniz kapsamlara bağlıdır.
photoslibrary.readonly, kullanıcının kitaplığındaki tüm medya öğelerine erişim izni verirphotoslibrary.readonly.appcreateddata, yalnızca uygulama tarafından oluşturulan medya öğelerine erişim sağlar
Medya öğeleri
mediaItem, Google Fotoğraflar kitaplığına yüklenen fotoğraf veya video gibi medyanın bir temsilidir. Üst düzey bir nesnedir ve özellikleri, temel medya türüne göre farklılık gösterebilir.
Aşağıdaki tabloda mediaItem özellikleri listelenmektedir:
| Özellikler | |
|---|---|
id |
Nesneyi tanımlamak için kullanılan kalıcı, sabit bir kimliktir. |
description |
Google Fotoğraflar'da görünen medya öğesinin açıklaması. |
baseUrl |
Ham baytlara erişmek için kullanılır. Daha fazla bilgi için Temel URL'ler başlıklı makaleyi inceleyin. |
productUrl |
Google Fotoğraflar'daki resmin bağlantısı. Bu bağlantı geliştirici tarafından değil, yalnızca kullanıcı tarafından açılabilir. URL'ler, kitaplıktaki bir medya öğesine yönlendirir. URL bir albüm aramasından alındıysa albümdeki öğeyi işaret eder. |
mimeType |
Medya türünü kolayca tanımlamaya yardımcı olmak için medya öğesinin türü (örneğin: image/jpg). |
filename |
Google Fotoğraflar uygulamasında kullanıcıya gösterilen medya öğesinin dosya adı (öğenin bilgi bölümünde). |
mediaMetadata |
Medyanın temel türüne (ör. photo veya video) göre değişir.
Yükü azaltmak için alan maskeleri kullanılabilir.
|
contributorInfo |
Bu alan yalnızca medya öğesi bu uygulama tarafından oluşturulan bir ortak albümdeyse ve kullanıcı Bu medya öğesini ekleyen kullanıcıyla ilgili bilgileri içerir. Ayrıntılı bilgi için Medya paylaşma başlıklı makaleyi inceleyin. |
Medya öğesi al
Bir medya öğesini almak için mediaItemId kullanarak mediaItems.get işlevini çağırın. İstek tek bir medya öğesi döndürür.
mediaItem, kimlik, açıklama ve URL gibi özellikleri içerir. photo veya video içindeki ek bilgiler, dosyadaki meta verilere bağlıdır. Tüm mülkler mevcut olmayabilir. ContributorInfo, paylaşılan bir albümün parçası olan öğelerin meta verilerini içerir. Bu alan yalnızca kullanıcının photoslibrary.sharing
yetkilendirme kapsamını verdiği paylaşılan bir albümün içeriğini listelerken dahil edilir.
Medya öğesi bir video ise öncelikle video dosyasının işlenmesi gerekir. mediaItem, mediaMetadata içinde video dosyasının işleme durumunu açıklayan bir status alanı içerir. Yeni yüklenen bir dosya, videoProcessingStatus değerini ilk olarak PROCESSING ile döndürür, ardından READY ile kullanılabilir. Video medya öğesinin baseUrl
video işlenene kadar kullanılamaz.
REST
Aşağıda bir GET isteği verilmiştir:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
Fotoğraf medya öğesi için yanıt şu şekilde görünür. Fotoğraf mülkü, fotoğraf öğelerinin meta verilerini içerir.
{
"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"
}
}
Bir video medya öğesinin yanıtı aşağıdaki gibi görünür. Video mülkü, video öğeleri için meta verileri içerir.
{
"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"
}
}
Java
Fotoğraf mülkü, fotoğraf öğelerinin meta verilerini içerir.
try {
// Get a media item using its ID
String mediaItemId = "...";
MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
// Get some properties from the retrieved media item
String id = item.getId();
String description = item.getDescription();
String baseUrl = item.getBaseUrl();
String productUrl = item.getProductUrl();
// ...
if (item.hasMediaMetadata()) {
// The media item contains additional metadata, such as the height and width
MediaMetadata metadata = item.getMediaMetadata();
long height = metadata.getHeight();
long width = metadata.getWidth();
Timestamp creationTime = metadata.getCreationTime();
// ...
if (metadata.hasPhoto()) {
// This media item is a photo and has additional photo metadata
Photo photoMetadata = metadata.getPhoto();
String cameraMake = photoMetadata.getCameraMake();
String cameraModel = photoMetadata.getCameraModel();
float aperture = photoMetadata.getApertureFNumber();
int isoEquivalent = photoMetadata.getIsoEquivalent();
// ...
}
}
if (item.hasContributorInfo()) {
// A user has contributed this media item to a shared album
ContributorInfo contributorInfo = item.getContributorInfo();
String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
String displayName = contributorInfo.getDisplayName();
}
} catch (ApiException e) {
// Handle error
}
Video mülkü, video öğeleri için meta verileri içerir.
try {
// Get a media item using its ID
String mediaItemId = "...";
MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
// Get some properties from the retrieved media item
String id = item.getId();
String description = item.getDescription();
String baseUrl = item.getBaseUrl();
String productUrl = item.getProductUrl();
// ...
if (item.hasMediaMetadata()) {
// The media item contains additional metadata, such as the height and width
MediaMetadata metadata = item.getMediaMetadata();
long height = metadata.getHeight();
long width = metadata.getWidth();
Timestamp creationTime = metadata.getCreationTime();
// ...
if (metadata.hasVideo()) {
// This media item is a video and has additional video metadata
Video videoMetadata = metadata.getVideo();
VideoProcessingStatus status = videoMetadata.getStatus();
if (status.equals(VideoProcessingStatus.READY)) {
// This video media item has been processed
String cameraMake = videoMetadata.getCameraMake();
String cameraModel = videoMetadata.getCameraModel();
double fps = videoMetadata.getFps();
// ...
}
}
}
if (item.hasContributorInfo()) {
// A user has contributed this media item to a shared album
ContributorInfo contributorInfo = item.getContributorInfo();
String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
String displayName = contributorInfo.getDisplayName();
}
} catch (ApiException e) {
// Handle error
}
PHP
Fotoğraf mülkü, fotoğraf öğelerinin meta verilerini içerir.
try {
// Get a media item using its ID
$mediaItemId = "...";
$item = $photosLibraryClient->getMediaItem($mediaItemId);
// Get some properties from the retrieved media item
$id = $item->getId();
$description = $item->getDescription();
$baseUrl = $item->getBaseUrl();
$productUrl = $item->getProductUrl();
// ...
$metadata = $item->getMediaMetadata();
if (!is_null($metadata)) {
// The media item contains additional metadata, such as the height and width
$height = $metadata->getHeight();
$width = $metadata->getWidth();
$creationTime = $metadata->getCreationTime();
// ...
$photoMetadata = $metadata->getPhoto();
if (!is_null($photoMetadata)) {
// This media item is a photo and has additional photo metadata
$cameraMake = $photoMetadata->getCameraMake();
$cameraModel = $photoMetadata->getCameraModel();
$aperture = $photoMetadata->getApertureFNumber();
$isoEquivalent = $photoMetadata->getIsoEquivalent();
// ...
}
}
$contributorInfo = $item->getContributorInfo();
if (!is_null($contributorInfo)) {
// A user has contributed this media item to a shared album
$profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
$displayName = $contributorInfo->getDisplayName();
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Video mülkü, video öğeleri için meta verileri içerir.
try {
// Get a media item using its ID
$mediaItemId = "...";
$item = $photosLibraryClient->getMediaItem($mediaItemId);
// Get some properties from the retrieved media item
$id = $item->getId();
$description = $item->getDescription();
$baseUrl = $item->getBaseUrl();
$productUrl = $item->getProductUrl();
// ...
$metadata = $item->getMediaMetadata();
if (!is_null($metadata)) {
// The media item contains additional metadata, such as the height and width
$height = $metadata->getHeight();
$width = $metadata->getWidth();
$creationTime = $metadata->getCreationTime();
// ...
$videoMetadata = $metadata->getVideo();
if (!is_null($videoMetadata)) {
// This media item is a video and has additional video metadata
if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
// This video media item has been processed
$cameraMake = $videoMetadata->getCameraMake();
$cameraModel = $videoMetadata->getCameraModel();
$fps = $videoMetadata->getFps();
// ...
}
}
}
$contributorInfo = $item->getContributorInfo();
if (!is_null($contributorInfo)) {
// A user has contributed this media item to a shared album
$profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
$displayName = $contributorInfo->getDisplayName();
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Birden fazla medya öğesi alma
Birden fazla medya öğesini tanımlayıcılarına göre almak için mediaItemId'ları kullanarak mediaItems.batchGet işlevini çağırın.
İstek, istekte sağlanan medya öğesi tanımlayıcılarının sırasına göre bir MediaItemResults listesi döndürür. Hata varsa her sonuçta MediaItem veya Status bulunur.
Tek bir çağrıda isteyebileceğiniz maksimum medya öğesi sayısı 50'dir. Medya öğeleri listesi, yinelenen tanımlayıcılar içermemelidir ve boş olamaz.
REST
Aşağıda, medya öğelerine başarılı ve başarısız erişimi gösteren bir GET isteği verilmiştir. Her medya öğesi tanımlayıcısını, istek kapsamında yeni bir mediaItemIds sorgu parametresi olarak belirtin:
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 isteği aşağıdaki yanıtı döndürür:
{
"mediaItemResults": [
{
"mediaItem": {
"id": "media-item-id",
...
}
},
{
"mediaItem": {
"id": "another-media-item-id",
...
}
},
{
"status": {
"code": 3,
"message": "Invalid media item ID."
}
}
]
}
Java
try {
// List of media item IDs to retrieve
List<String> mediaItemIds = Arrays
.asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");
// Get a list of media items using their IDs
BatchGetMediaItemsResponse response = photosLibraryClient
.batchGetMediaItems(mediaItemIds);
// Loop over each result
for (MediaItemResult result : response.getMediaItemResultsList()) {
// Each MediaItemresult contains a status and a media item
if (result.hasMediaItem()) {
// The media item was successfully retrieved, get some properties
MediaItem item = result.getMediaItem();
String id = item.getId();
// ...
} else {
// If the media item is not set, an error occurred and the item could not be loaded
// Check the status and handle the error
Status status = result.getStatus();
// ...
}
}
} catch (ApiException e) {
// Handle error
}
PHP
try {
// List of media item IDs to retrieve
$mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];
// Get a list of media items using their IDs
$response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);
// Loop over each result
foreach ($response->getMediaItemResults() as $itemResult) {
// Each MediaItemresult contains a status and a media item
$mediaItem = $itemResult->getMediaItem();
if(!is_null($mediaItem)){
// The media item was successfully retrieved, get some properties
$id = $mediaItem->getId();
// ...
} else {
// If the media item is null, an error occurred and the item could not be loaded
}
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Temel URL'ler
Google Fotoğraflar Kitaplığı API'sindeki temel URL'ler, medya öğelerinin baytlarına erişmenize olanak tanır. Uygulamanız, çeşitli temel URL'leri kullanarak medya öğelerini indirebilir veya uygulamanızda medya öğelerini görüntüleyebilir. Temel URL'ler, albümleri listelediğinizde veya medya öğelerine eriştiğinizde yanıta dahil edilen dizelerdir. 60 dakika boyunca geçerlidirler ve olduğu gibi kullanılamadığından ek parametreler gerektirirler.
Çeşitli temel URL'ler şunlardır:
baseUrl: Fotoğrafa, videonun küçük resmine doğrudan erişebilir veya video baytlarını indirebilirsiniz.coverPhotoBaseUrl: Albümün kapak fotoğrafına doğrudan erişin.profilePictureBaseUrl:mediaItemsahibinin profil fotoğrafına doğrudan erişin.
Resim temel URL'leri
Resim temel URL'leriyle kullanabileceğiniz seçeneklerin listesi aşağıda verilmiştir:
| Parametre | |
|---|---|
w, h |
Açıklama Genişlik ( Fotoğraf veya video küçük resmi gibi bir resim medya öğesine erişmek için uygulamanızda görüntülemeyi planladığınız boyutları belirtmeniz gerekir (böylece resim, en boy oranı korunarak bu boyutlara ölçeklendirilebilir). Bunun için temel URL'yi, örneklerde gösterildiği gibi gerekli boyutlarınızla birleştirin. Örnekler: base-url=wmax-width-hmax-height 2048 pikselden geniş ve 1024 pikselden yüksek olmayan bir medya öğesi göstermek için aşağıdaki örneği inceleyin: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Açıklama Kırpma, Resmi, belirttiğiniz tam genişlik ve yükseklik boyutlarına göre kırpmak istiyorsanız temel URL'yi zorunlu Boyut (piksel cinsinden) [1, 16383] aralığında olmalıdır. Resmin genişliği veya yüksekliği, istenen boyutu aşarsa resim küçültülür ve kırpılır (en boy oranı korunacaktır). Örnekler: base-url=wmax-width-hmax-height-c Bu örnekte uygulama, tam olarak 256 piksel genişliğinde ve 256 piksel yüksekliğinde bir medya öğesi (ör. küçük resim) gösterir: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Açıklama İndirme, Resmi, konum meta verileri dışındaki tüm Exif meta verilerini koruyarak indirmek istiyorsanız temel URL'yi Örnekler: base-url=d Bu örnekte uygulama, konum meta verileri dışındaki tüm meta verileri içeren bir resim indirir: https://lh3.googleusercontent.com/p/Az....XabC=d |
Video temel URL'leri
Video ana URL'leriyle kullanabileceğiniz seçeneklerin listesi aşağıda verilmiştir:
| Parametre | |
|---|---|
dv |
Açıklama
dv parametresi, orijinal videonun yüksek kaliteli, kod dönüştürülmüş bir sürümünü ister. Parametre, w ve h parametreleriyle uyumlu değildir. Video indirmelerinin temel URL'lerinin bayt döndürmesi birkaç saniye sürebilir. Bu parametreyi kullanmadan önce medya öğelerinin Örnekler: base-url=dv Aşağıdaki örnekte bir videonun baytlarının nasıl indirileceği gösterilmektedir: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w, h, c ve
d |
Açıklama Videonun küçük resmine erişmek için resim temel URL parametrelerinden herhangi birini kullanın. Varsayılan olarak tüm video küçük resimlerinde bir oynatma düğmesi yer paylaşımı bulunur. Bu yer paylaşımını kaldırmak için -no parametresine bakın. Örnekler: Örnekler için resim temel URL'leri tablosuna bakın. |
no |
Açıklama Küçük resim yer paylaşımını kaldır Bir videonun küçük resmini oynatma düğmesi yer paylaşımı olmadan almak istiyorsanız temel URL'yi no parametresiyle birleştirin. no parametresi, görüntü temel URL parametrelerinden en az biri ile kullanılmalıdır. Örnekler: base-url=wmax-width-hmax-height-no Aşağıdaki örnekte, tam olarak 1.280 piksel genişliğinde ve 720 piksel yüksekliğinde olan ve oynatma düğmesi yer almayan bir video küçük resmi gösterilmektedir: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Hareketli fotoğraf temel URL'leri
Hareketli fotoğraflar hem fotoğraf hem de video öğeleri içerir. Hareketli fotoğraf baseUrl istekleri için resim temel URL'lerindeki veya video temel URL'lerindeki parametreleri kullanabilirsiniz.
| Parametre | |
|---|---|
dv |
Açıklama Hareketli fotoğraf medya öğesinin video öğesini almak için |
w, h, c ve
d |
Açıklama Bir hareketli fotoğraf medya öğesinin fotoğraf öğesini almak için resim temel URL'lerinin biçimini kullanın. |