Truy cập các mục nội dung nghe nhìn

Sau khi thực hiện lệnh gọi để liệt kê nội dung của thư viện ảnh hoặc album, thay vì lưu trữ các mục nội dung đa phương tiện được trả về, ứng dụng của bạn sẽ lưu trữ mã nhận dạng của các mục nội dung đa phương tiện đó. Điều này là do nội dung của các mục đa phương tiện có thể và sau một khoảng thời gian nhất định, các URL trong phản hồi sẽ hết hạn. Mã nhận dạng nội dung nghe nhìn xác định duy nhất một nội dung nghe nhìn, chẳng hạn như ảnh hoặc video trong thư viện của người dùng.

Xin lưu ý rằng ứng dụng của bạn không được lưu ảnh hoặc video của người dùng vào bộ nhớ đệm trong thời gian dài. Tuy nhiên, tuỳ thuộc vào trường hợp sử dụng, bạn có thể lưu trữ hoặc lưu vào bộ nhớ đệm mã nhận dạng mục nội dung nghe nhìn trong thời gian cần thiết. Bạn cũng nên lưu ý rằng quyền truy cập vào hàm người dùng dữ liệu chịu sự điều chỉnh của quyền riêng tư nghĩa vụ bổ sung.

Phạm vi uỷ quyền bắt buộc

Để truy cập vào các mục nội dung đa phương tiện, ứng dụng của bạn phải yêu cầu ít nhất một trong những yêu cầu sau phạm vi uỷ quyền. Quyền truy cập vào các mục nội dung đa phương tiện được trả về trong phản hồi phụ thuộc vào phạm vi mà bạn đã yêu cầu.

  • photoslibrary.readonly cho phép truy cập vào tất cả các mục nội dung nghe nhìn trong thư viện của người dùng
  • photoslibrary.readonly.appcreateddata chỉ cho phép truy cập vào các mục nội dung đa phương tiện do ứng dụng tạo ra

Mục nội dung nghe nhìn

mediaItem là một nội dung đa phương tiện (chẳng hạn như ảnh hoặc video) đã được tải lên thư viện Google Photos. Đây là đối tượng cấp cao nhất và các thuộc tính của đối tượng đó có thể khác nhau tuỳ theo loại nội dung nghe nhìn cơ bản.

Bảng sau đây liệt kê các thuộc tính mediaItem:

Thuộc tính
id Mã nhận dạng cố định, ổn định dùng để xác định đối tượng.
description Nội dung mô tả về mục nội dung nghe nhìn như trong Google Photos.
baseUrl Được dùng để truy cập các byte thô. Để biết thêm thông tin, hãy xem bài viết URL cơ sở.
productUrl

Đường liên kết đến hình ảnh trong Google Photos. Đường liên kết này không được do nhà phát triển mở mà chỉ người dùng mở. URL trỏ đến một mục nội dung nghe nhìn trong thư viện. Nếu URL được truy xuất từ tìm kiếm album, URL đó trỏ đến mục trong album.

mimeType Loại mục nội dung đa phương tiện giúp dễ dàng xác định loại nội dung nghe nhìn (ví dụ: image/jpg).
filename Tên tệp của mục nội dung nghe nhìn hiển thị cho người dùng trong ứng dụng Google Photos (trong phần thông tin của mục).
mediaMetadata Thay đổi tuỳ thuộc vào loại nội dung nghe nhìn cơ bản, chẳng hạn như photo hoặc video. Để giảm tải trọng, bạn có thể sử dụng mặt nạ trường.
contributorInfo

Trường này chỉ được điền nếu mục nội dung nghe nhìn nằm trong một album chia sẻ do ứng dụng này tạo và người dùng đã cấp phạm vi photoslibrary.sharing.

Chứa thông tin về cộng tác viên đã thêm nội dung nghe nhìn này mục. Để biết thêm thông tin chi tiết, hãy xem bài viết Chia sẻ nội dung nghe nhìn.

Lấy một mục nội dung nghe nhìn

Để truy xuất một mục nội dung đa phương tiện, hãy gọi mediaItems.get bằng mediaItemId. Yêu cầu trả về một mục nội dung nghe nhìn.

mediaItem chứa các thuộc tính như mã nhận dạng, nội dung mô tả và URL. Chiến lược phát hành đĩa đơn thông tin bổ sung trong photo hoặc video là dựa trên siêu dữ liệu trong tệp. Bạn có thể không sử dụng được một số thuộc tính. ContributorInfo chứa siêu dữ liệu cho các mục thuộc một album chia sẻ. Trường này chỉ được đưa vào khi liệt kê nội dung của album chia sẻ mà người dùng đã cấp photoslibrary.sharing phạm vi uỷ quyền.

Nếu mục nội dung nghe nhìn là video, thì trước tiên, bạn phải xử lý tệp video. Chiến lược phát hành đĩa đơn mediaItem chứa trường status bên trong mediaMetadata, trường này mô tả trạng thái xử lý của tệp video. Tệp mới tải lên sẽ trả về videoProcessingStatus với giá trị PROCESSING trước khi chuyển sang READY để sử dụng. baseUrl mục nội dung đa phương tiện video sẽ không có sẵn cho đến khi video được xử lý.

REST

Dưới đây là yêu cầu GET:

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

Câu trả lời cho một mục nội dung nghe nhìn dạng ảnh sẽ có dạng như sau. Ảnh thuộc tính chứa siêu dữ liệu cho các mục ảnh.

{
  "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"
  }
}

Phản hồi cho mục nội dung đa phương tiện dạng video có dạng như sau. Video thuộc tính chứa siêu dữ liệu cho các mục video.

{
  "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

Thuộc tính ảnh chứa siêu dữ liệu cho các mục ảnh.

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
}

Thuộc tính video chứa siêu dữ liệu cho các mục video.

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

Thuộc tính ảnh chứa siêu dữ liệu cho các mục ảnh.

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
}

Tài sản video chứa siêu dữ liệu cho các mục video.

  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
}

Tải nhiều mục nội dung nghe nhìn

Để truy xuất nhiều mục nội dung nghe nhìn theo giá trị nhận dạng của các mục đó, hãy gọi mediaItems.batchGet bằng mediaItemId.

Yêu cầu trả về một danh sách MediaItemResults theo thứ tự của các giá trị nhận dạng mục nội dung đa phương tiện được cung cấp trong yêu cầu. Từng kết quả chứa MediaItem hoặc Status nếu đã xảy ra lỗi.

Số lượng mục nội dung nghe nhìn tối đa mà bạn có thể yêu cầu trong một lệnh gọi là 50. Danh sách mục nội dung đa phương tiện không được chứa giá trị nhận dạng trùng lặp và không được để trống.

REST

Dưới đây là yêu cầu GET cho thấy việc truy cập thành công và không thành công vào mục nội dung nghe nhìn. Chỉ định từng giá trị nhận dạng mục nội dung đa phương tiện là giá trị mới Tham số truy vấn mediaItemIds trong yêu cầu:

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

Yêu cầu GET trả về phản hồi sau:

{
  "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
}

URL cơ sở

Các URL cơ sở trong API Thư viện Google Photos cho phép bạn truy cập vào các byte của nội dung đa phương tiện mục. Bằng cách sử dụng nhiều URL cơ sở, ứng dụng của bạn có thể tải các mục nội dung nghe nhìn xuống hoặc hiển thị các mục nội dung nghe nhìn trong ứng dụng. URL cơ sở là các chuỗi được đưa vào phản hồi khi bạn liệt kê các album hoặc truy cập vào các mục nội dung nghe nhìn. Đó là có hiệu lực trong 60 phút và yêu cầu các tham số bổ sung vì chúng không thể được sử dụng dưới dạng của chúng tôi.

Có các URL cơ sở sau:

  • baseUrl: Truy cập trực tiếp vào ảnh, hình thu nhỏ của video hoặc tải các byte video xuống.
  • coverPhotoBaseUrl: Truy cập trực tiếp vào ảnh bìa của album.
  • profilePictureBaseUrl: Truy cập trực tiếp vào ảnh hồ sơ của chủ sở hữu mediaItem.

URL cơ sở của hình ảnh

Dưới đây là danh sách các lựa chọn mà bạn có thể sử dụng với URL cơ sở của hình ảnh:

Thông số
w, h

Nội dung mô tả

Các tham số chiều rộng, w và chiều cao, h.

Để truy cập vào một mục đa phương tiện của hình ảnh, chẳng hạn như ảnh hoặc hình thu nhỏ cho Bạn phải chỉ định kích thước mà bạn dự định hiển thị ứng dụng của bạn (để hình ảnh có thể được điều chỉnh theo tỷ lệ mà vẫn giữ nguyên tỷ lệ khung hình). Để thực hiện việc này, nối URL cơ sở với các phương diện bắt buộc như được minh hoạ trong ví dụ.

Ví dụ:

base-url=wmax-width-hmax-height

Dưới đây là ví dụ về cách hiển thị một mục nội dung nghe nhìn không rộng hơn 2048 px và không cao hơn 1024 px:

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

Nội dung mô tả

Phần cắt, tham số c.

Nếu bạn muốn cắt hình ảnh theo đúng chiều rộng và chiều cao mà bạn đã chỉ định, hãy nối URL cơ sở với thông số -c không bắt buộc cùng với thông số bắt buộc Tham số w và h.

Kích thước (tính bằng pixel) phải nằm trong khoảng [1, 16383]. Nếu chiều rộng hoặc chiều cao của hình ảnh vượt quá kích thước yêu cầu, hình ảnh được thu nhỏ và cắt bớt (duy trì tỷ lệ khung hình).

Ví dụ:

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

Trong ví dụ này, ứng dụng hiển thị một mục nội dung đa phương tiện rộng chính xác 256 px x cao 256 px, chẳng hạn như hình thu nhỏ:

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

Nội dung mô tả

Tệp tải xuống, tham số d.

Nếu bạn muốn tải hình ảnh xuống và giữ lại tất cả siêu dữ liệu Exif ngoại trừ siêu dữ liệu vị trí, hãy nối URL cơ sở với tham số d.

Ví dụ:

base-url=d

Trong ví dụ này, ứng dụng sẽ tải một hình ảnh xuống có tất cả siêu dữ liệu ngoại trừ siêu dữ liệu vị trí:

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

URL cơ sở của video

Dưới đây là danh sách các tuỳ chọn bạn có thể sử dụng với URL cơ sở của video:

Thông số
dv

Nội dung mô tả

Để truy cập các byte của video mediaItem, hãy nối các byte baseUrl có video tải xuống, dv .

Tham số dv yêu cầu phiên bản video gốc đã chuyển mã, chất lượng cao. Tham số này không tương thích với các tham số w và h.

URL cơ sở để tải video xuống có thể mất vài giây để trả về các byte.

Trước khi sử dụng tham số này, hãy kiểm tra để đảm bảo trường mediaMetadata.status của các mục nội dung nghe nhìn là READY. Ngược lại, nếu mục nội dung đa phương tiện của bạn chưa hoàn tất quá trình xử lý. Bạn có thể nhận được .

Ví dụ:

base-url=dv

Ví dụ sau đây minh hoạ cách tải các byte của một video:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c và d

Nội dung mô tả

Để truy cập vào hình thu nhỏ của video, hãy sử dụng bất kỳ thông số URL cơ sở của hình ảnh nào.

Theo mặc định, tất cả hình thu nhỏ video đều có một lớp phủ nút phát. Xem thông số -no để loại bỏ lớp phủ này.

Ví dụ:

Tham khảo bảng URL cơ sở của hình ảnh để có các ví dụ.
no

Nội dung mô tả

Lớp phủ xoá hình thu nhỏ, tham số no.

Nếu bạn muốn truy xuất hình thu nhỏ của video khi không có lớp phủ của một nút phát, hãy nối URL cơ sở với ký tự no .

Bạn phải sử dụng tham số no với ít nhất một trong các tham số URL cơ sở của hình ảnh.

Ví dụ:

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

Ví dụ sau đây cho thấy một hình thu nhỏ video có chiều rộng chính xác là 1280 px và chiều cao là 720 px, không bao gồm lớp phủ nút phát:

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

URL cơ sở ảnh động

Ảnh chuyển động chứa cả phần tử ảnh và video. Bạn có thể sử dụng các tham số của URL cơ sở hình ảnh hoặc URL cơ sở của video cho các yêu cầu baseUrl về ảnh chuyển động.

Thông số
dv

Nội dung mô tả

Để truy xuất phần tử video của một mục nội dung đa phương tiện ảnh động, hãy sử dụng thông số dv như khi bạn tải xuống từ URL cơ sở video.
w, h, c và d

Nội dung mô tả

Để truy xuất phần tử ảnh của một mục nội dung nghe nhìn dạng ảnh chuyển động, hãy sử dụng định dạng cho URL cơ sở hình ảnh.