Uygulamanız döndürülen medya öğelerini depolamak yerine bir fotoğraf kitaplığının veya albümün içeriğini listelemek için çağrı yaptıktan sonra 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 fotoğraf veya video gibi medya öğelerini 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 süre boyunca depolayabilir veya önbelleğe alabilirsiniz. Kullanıcı verilerine erişimin gizlilik yükümlülüklerine tabi olduğunu da 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
Medya öğeleri
mediaItem, Google Fotoğraflar kitaplığına yüklenen fotoğraf veya video gibi medya öğelerini temsil eder. Bu, ü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 listelenmiştir:
| Özellikler | |
|---|---|
id |
Nesneyi tanımlamak için kullanılan kalıcı ve sabit bir kimliktir. |
description |
Medya öğesinin Google Fotoğraflar'da görünen açıklaması. |
baseUrl |
Ham baytlara erişmek için kullanılır. Daha fazla bilgi için Temel URL'ler konusuna bakın. |
productUrl |
Google Fotoğraflar'daki resmin bağlantısı. Bu bağlantı geliştirici tarafından açılamaz, yalnızca kullanıcı tarafından açılabilir. URL'ler kitaplıktaki bir medya öğesine işaret eder. URL bir albüm aramasından alındıysa albümdeki öğeyi işaret eder. |
mimeType |
Medya türünün kolayca tanımlanmasına yardımcı olan medya öğesinin türü (örneğin: image/jpg). |
filename |
Kullanıcıya Google Fotoğraflar uygulamasında (öğenin bilgi bölümünde) gösterilen medya öğesinin dosya adı. |
mediaMetadata |
Temel medya türüne (ör. photo veya video) bağlı olarak 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 paylaşılan bir albümdeyse ve kullanıcı Bu medya öğesini ekleyen katkıda bulunan hakkındaki bilgileri içerir. Daha fazla ayrıntı için Medya paylaşma başlıklı makaleyi inceleyin. |
Medya öğesi alma
Bir medya öğesini almak için mediaItemId kullanarak mediaItems.get yöntemini ç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 özellikler mevcut olmayabilir. ContributorInfo, paylaşılan bir albümün parçası olan öğelere ait meta verileri içerir. Bu alan yalnızca kullanıcının photoslibrary.sharing
yetkilendirme kapsamını verdiği paylaşılan bir albümün içerikleri listelenirken eklenir.
Medya öğesi bir videoysa önce video dosyası işlenmelidir. mediaItem, mediaMetadata içinde video dosyasının işleme durumunu açıklayan bir status alanı içerir. Yeni yüklenen bir dosya, kullanım READY olmadan önce PROCESSING değerine sahip videoProcessingStatus değerini döndürür. Bir video medya öğesinin baseUrl özelliği, 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
Bir fotoğraf medya öğesinin yanıtı şuna benzer: Fotoğraf özelliği, 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ı şuna benzer: Video özelliği, video öğ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",
"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 özelliği, fotoğraf öğelerine ilişkin 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.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 özelliği, video öğ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.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 özelliği, fotoğraf öğelerine ilişkin 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();
// ...
$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 özelliği, video öğ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();
// ...
$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 çok medya öğesini alma
Birden fazla medya öğesini tanımlayıcılarına göre almak için mediaItemId kullanarak mediaItems.batchGet yöntemini çağırın.
İstek, istekte sağlanan medya öğesi tanımlayıcılarının sırasına göre MediaItemResults listesini döndürür. Her sonuç bir MediaItem veya hata varsa Status içerir.
Bir aramada en fazla 50 medya öğesi isteyebilirsiniz. Medya öğeleri listesi, yinelenen tanımlayıcılar içermemeli ve boş olamaz.
REST
Medya öğelerine başarılı ve başarısız erişimi gösteren bir GET isteğini burada bulabilirsiniz. Her medya öğesi tanımlayıcısını, isteğin parçası olarak 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 Photos Library API'deki 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ızın içindeki medya öğelerini görüntüleyebilir. Temel URL'ler, albümleri listelediğinizde veya medya öğelerine eriştiğinizde yanıta dahil edilen dizelerdir. Bunlar 60 dakika boyunca geçerlidir ve olduğu gibi kullanılamayacağı için ek parametreler gerektirir.
Çeşitli temel URL'ler şunlardır:
baseUrl: Bir videonun fotoğrafına, küçük resmine doğrudan erişebilir veya video baytlarını indirebilirsiniz.coverPhotoBaseUrl: Albümün kapak fotoğrafına doğrudan erişebilir.profilePictureBaseUrl: BirmediaItemsahibinin profil fotoğrafına doğrudan erişebilirsiniz.
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, Resim medya öğesine (ör. bir videonun fotoğrafı veya küçük resmi) erişmek için uygulamanızda görüntülemeyi planladığınız boyutları belirtmeniz gerekir (böylece, en boy oranı korunarak resim bu boyutlara göre ölçeklendirilebilir). Bunu yapmak için temel URL'yi, örneklerde gösterildiği gibi gerekli boyutlarla birleştirin. Örnekler: base-url=wmax-width-hmax-height Aşağıda, 2048 pikselden geniş ve 1.024 pikselden uzun olmayan bir medya öğesini göstermeye ilişkin bir örnek verilmiştir: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Açıklama Kırpma, Resmi tam olarak belirttiğiniz genişlik ve yükseklik boyutlarına göre kırpmak isterseniz 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ı korunarak). Ö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 görüntüler (örneğin, küçük resim): https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Açıklama İndirme, Resmi, konum meta verileri hariç tüm EXIF meta verilerini saklayacak şekilde indirmek isterseniz temel URL'yi Örnekler: base-url=d Bu örnekte uygulama, konum meta verileri hariç tüm meta verilere sahip bir resim indirir: https://lh3.googleusercontent.com/p/Az....XabC=d |
Video temel URL'leri
Video temel URL'leriyle kullanabileceğiniz seçeneklerin listesini burada bulabilirsiniz:
| Parametre | |
|---|---|
dv |
Açıklama Bir videonun ( dv parametresi, orijinal videonun yüksek kaliteli, dönüştürülmüş bir sürümünü ister. Parametre, w ve h parametreleriyle uyumlu değildir. Video indirmeleri için temel URL'lerin bayt döndürmesi birkaç saniyeyi bulabilir. Bu parametreyi kullanmadan önce medya öğelerinin Örnekler: base-url=dv Aşağıdaki örnekte bir videonun baytlarını nasıl indireceğiniz 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 görüntü temel URL parametrelerinden herhangi birini kullanın. Varsayılan olarak tüm video küçük resimleri, bir oynatma düğmesinin yer paylaşımını içerir. Bu yer paylaşımını kaldırmak için -no parametresine bakın. Örnekler: Örnekler için görüntü 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üğmesinin yer paylaşımı olmadan almak istiyorsanız temel URL'yi no parametresiyle birleştirin. no parametresi, resim temel URL parametrelerinden en az biriyle kullanılmalıdır. Örnekler: base-url=wmax-width-hmax-height-no Aşağıdaki örnekte, tam olarak 1280 piksel genişliğinde ve 720 piksel yüksekliğinde olan ve oynatma düğmesi yer paylaşımı içermeyen bir video küçük resmi gösterilmektedir: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Hareketli fotoğraf tabanı URL'leri
Hareketli fotoğraflar hem fotoğraf hem de video öğeleri içerir. Hareketli fotoğraf baseUrl istekleri için görüntü temel URL'lerindeki veya video temel URL'lerindeki parametreleri kullanabilirsiniz.
| Parametre | |
|---|---|
dv |
Açıklama Bir 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. |