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

Sau khi gọi điện đến liệt kê nội dung của một thư viện ảnh hoặc album, thay vì lưu trữ các mục phương tiện được trả về, ứng dụng của bạn sẽ lưu trữ Mã 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. Chiến lược phát hành đĩa đơn mã mục nội dung đa phương tiện xác định duy nhất một mục nội dung đa phương tiện, chẳng hạn như ảnh hoặc video bên trong thư viện của người dùng.

Lưu ý rằng ứng dụng của bạn không nên lưu ảnh hoặc video của người dùng vào bộ nhớ đệm trong thời gian dài cụ thể, nhưng tuỳ thuộc vào trường hợp sử dụng của mình, bạn có thể lưu trữ hoặc lưu mã mục nội dung đa phương tiện vào bộ nhớ đệm dài bằng . 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ả mục nội dung đa phương tiện trong thư viện
  • 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

Đáp mediaItem là nội dung đại diện cho nội dung nghe nhì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 nó 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, cố định dùng để xác định đối tượng.
description Nội dung mô tả mục nội dung đa phương tiện như bên 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 đa phương tiệ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 đa phương tiện mà người dùng nhìn thấy trong Google Photos (trong phần thông tin của mặt hàng).
mediaMetadata Khác nhau 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 sẵ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 quyền 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, hãy xem bài viết Chia sẻ nội dung nghe nhìn.

Tải một mục nội dung nghe nhìn

Để truy xuất một mục nội dung nghe nhìn, hãy gọi mediaItems.get bằng cách sử dụ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 nằm trong album được 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, tệp video phải được xử lý. 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 được tải lên sẽ trả về videoProcessingStatus với giá trị PROCESSING trước, sau đó là 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ý.

Kiến trúc chuyển trạng thái đại diện (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

Phản hồi cho mục nội dung nghe nhìn dạng ảnh 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
}

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
  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 đa phương tiện theo giá trị nhận dạng, hãy gọi mediaItems.batchGet bằng cách sử dụ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.

Kiến trúc chuyển trạng thái đại diện (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. 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 của bạn. URL cơ sở là các chuỗi được đưa vào phản hồi khi bạn liệt kê album hoặc truy cập vào các mục nội dung đa phương tiệ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ó nhiều URL cơ sở:

  • baseUrl: Truy cập trực tiếp vào ảnh, hình thu nhỏ của một 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ả

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

Để 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

Sau đây là ví dụ về cách hiển thị một mục nội dung đa phương tiện không rộng hơn 2048 px và 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 (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 tải xuống một hình ảnh 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 mà 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 .

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

URL cơ sở cho việc tải video xuống có thể mất vài giây để byte trả về. Mặc định sử dụng phương thức mã hoá H.264 cho video tải xuống. Nếu mã hoá H.264 không thành công, thì VP9 sẽ được sử dụng.

Trước khi sử dụng tham số này, hãy kiểm tra xem các mục nội dung đa phương tiện Trường mediaMetadata.status 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ở hình ảnh nào.

Theo mặc định, tất cả hình thu nhỏ video đều chứa lớp phủ của một lần 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ả

Xoá lớp phủ 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 .

Tham số no phải được dùng với ít nhất một trong thời gian tham số URL của cơ sở hình ảnh.

Ví dụ:

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

Ví dụ sau đây hiển thị một hình thu nhỏ video có kích thước chính xác là 1280 px x 720 px và không có 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ả thành phần ả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 nghe nhìn dạng ảnh chuyển động, hãy sử dụng dv giống như bạn tải xuống từ URL cơ sở của 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.