Döndürülen medya öğelerini depolamak yerine fotoğraf kitaplığının veya albümün içeriğini listelemek için arama yaptıktan sonra uygulamanız, 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 fotoğraf veya video gibi bir medya öğesini benzersiz şekilde tanımlar.
Uygulamanızın, kullanıcının fotoğrafını veya videosunu uzun süre boyunca önbellekte tutmaması gerektiğini, ancak kullanım alanınıza bağlı olarak medya öğesi kimliğini gerektiği kadar depolayabileceğinizi veya önbelleğe alabileceğinizi unutmayın. Ayrıca, 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.appcreateddatayalnızca uygulama tarafından oluşturulan medya öğelerine erişim izni verir
Medya öğeleri
mediaItem
Google Fotoğraflar kitaplığına yüklenmiş fotoğraf veya video gibi medyanın temsilidir. Bu üst düzey bir nesnedir ve özellikleri temeldeki 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ı ve kararlı kimlik. |
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 bölümünü 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 öğesini işaret eder. URL, bir albüm aramasından alındıysa albüm içindeki öğeye işaret eder. |
mimeType |
Medya türünün kolayca tanımlanmasına yardımcı olacak 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ündedir). |
mediaMetadata |
Medyanın temel türüne (ör. photo veya video) bağlıdır.
Yükü azaltmak için alan maskeleri kullanılabilir.
|
contributorInfo |
Bu alan, yalnızca medya öğesi bu uygulama tarafından oluşturulan bir paylaşılan albümde yer alıyorsa ve kullanıcı Bu medya öğesini ekleyen katkıda bulunanla ilgili bilgileri içerir. Daha ayrıntılı bilgi için Medya paylaşma başlıklı makaleye bakın. |
Medya öğesi alma
Medya öğesini almak için mediaItemId'yi 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 dayalıdır. Bazı tesisler bulunmayabilir. 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ği listelenirken dahil edilir.
Medya öğesi bir video ise önce video dosyasının işlenmesi gerekir. mediaItem, mediaMetadata içinde video dosyasının işlenme durumunu açıklayan bir status alanı içerir. Yeni yüklenen bir dosya, kullanım için READY tarihinden önce ilk olarak PROCESSING değeriyle videoProcessingStatus değerini döndürür. Bir video medya öğesinin baseUrl özelliği, video işlenene kadar kullanılamaz.
REST
GET isteği:
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ı şu şekildedir: Fotoğraf özelliği, fotoğraf öğelerine ait 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",
"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ı şu şekildedir: 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 öğesi alma
Tanımlayıcılarına göre birden fazla medya öğesi almak için
mediaItemId öğelerini 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ç, hata varsa MediaItem veya Status içerir.
Bir görüşmede isteyebileceğiniz maksimum medya öğesi sayısı 50'dir. Medya öğeleri listesi yinelenen tanımlayıcılar içermemelidir ve boş olamaz.
REST
Medya öğelerine başarılı ve başarısız erişimi gösteren bir GET isteğini burada görebilirsiniz. Her medya öğesi tanımlayıcısını, isteğin bir 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 Fotoğraflar Kitaplığı API'sındaki 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ızdaki medya öğelerini görüntüleyebilir. Temel URL'ler, albümleri listelerken veya medya öğelerine eriştiğinizde yanıta dahil edilen dizelerdir. Bunlar 60 dakika geçerlidir ve oldukları gibi kullanılamadığı için ek parametreler gerektirir.
Çeşitli temel URL'ler şunlardır:
baseUrl: Bir fotoğrafa veya videonun küçük resmine doğrudan erişebilir ya da video baytlarını indirebilirsiniz.coverPhotoBaseUrl: Albümün kapak fotoğrafına doğrudan erişin.profilePictureBaseUrl: Doğrudan birmediaItemkullanıcısının profil fotoğrafına 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, Videoda kullanılacak fotoğraf veya küçük resim 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çeklenebilir). Bunu yapmak için temel URL'yi örneklerde gösterildiği gibi gerekli boyutlarınızla birleştirin. Örnekler: base-url=wmax-width-hmax-height Aşağıda, 2048 pikselden daha geniş olmayan ve 1024 pikselden uzun olmayan bir medya öğesi görüntülemek için bir örnek verilmiştir: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Açıklama Kırp, 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şıyorsa resim küçültülüp kırpılır (en boy oranı korunur). Ö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 küçük resim gibi medya öğesi göstermektedir: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Açıklama İndirme parametresi Konum meta verileri hariç tüm Exif meta verilerini tutan resmi indirmek isterseniz temel URL'yi Örnekler: base-url=d Bu örnekte uygulama, konum meta verileri hariç tüm meta verileri içeren bir resim indirir: https://lh3.googleusercontent.com/p/Az....XabC=d |
Video temel URL'leri
Video temel URL'leriyle kullanabileceğiniz seçeneklerin listesi aşağıda verilmiştir:
| Parametre | |
|---|---|
dv |
Açıklama
dv parametresi, orijinal videonun kod dönüştürmesi yapılmış yüksek bir sürümünü ister. Parametre, w ve h parametreleriyle uyumlu değildir. Video indirmeleri için temel URL'lerin baytların döndürülmesi birkaç saniye sürebilir. Bu parametreyi kullanmadan önce, medya öğelerinin Örnekler: base-url=dv Aşağıdaki örnekte bir videonun baytları 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 tabanı URL parametrelerinden birini kullanın. Varsayılan olarak, tüm video küçük resimleri bir oynatma düğmesi yer paylaşımı içerir. 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 kaldırma yer paylaşımı, Bir videonun küçük resmini, oynatma düğmesi yer paylaşımı olmadan almak istiyorsanız temel URL'yi no parametresiyle birleştirin. no parametresi, image Base 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 resim temel URL'lerindeki veya video taban URL'lerindeki parametreleri kullanabilirsiniz.
| Parametre | |
|---|---|
dv |
Açıklama Hareketli fotoğraf medya öğesinin video öğesini almak için
video temel URL'lerinden indirdiğiniz gibi |
w, h, c ve
d |
Açıklama Hareketli fotoğraf medya öğesinin fotoğraf öğesini almak için resim tabanı URL'leri biçimini kullanın. |