Tambahkan pengayaan

Pengayaan memungkinkan aplikasi mengontrol struktur dan presentasi foto dalam album di Google Foto. Anotasi memungkinkan Anda untuk menyajikan konteks tambahan kepada pengguna melalui teks atau anotasi lokasi, dan mengurutkan/mengelompokkan gambar yang menceritakan sebuah kisah bersama-sama.

Cakupan otorisasi yang diperlukan

Untuk menambahkan pengayaan, setidaknya salah satu cakupan berikut diperlukan:

  • photoslibrary.appendonly
  • photoslibrary.library
  • photoslibrary.sharing

Untuk setiap cakupan, panggilan enrichAlbum dibatasi hanya untuk album yang dibuat oleh aplikasi.

Saat menggunakan cakupan .sharing, enrichAlbum dibatasi untuk situasi saat developer bertindak atas nama pemilik album bersama.

Jenis pengayaan

Google Foto mendukung tiga jenis pengayaan dalam album: teks, lokasi, dan peta.

Pengayaan teks

Pengayaan teks adalah string teks biasa yang dapat disisipkan untuk menganotasi album.

Screenshot pengayaan teks yang ditampilkan di Google Foto

Pengayaan lokasi

Pengayaan lokasi adalah penanda dan nama tempat yang dapat disisipkan untuk memberi anotasi lokasi.

Screenshot pengayaan lokasi yang ditampilkan di Google Foto

Pengayaan peta

Pengayaan peta adalah peta dengan tempat asal dan tujuan tertentu yang dapat disisipkan dalam album.

Screenshot pengayaan peta yang ditampilkan di Google Foto

Posisi

Untuk menyisipkan item media dan pengayaan album, tentukan posisi album. Posisi bersifat opsional untuk item media, tetapi harus ditentukan untuk pengayaan album.

Posisi hanya dapat ditentukan saat membuat item media atau menambahkan pengayaan. Item media yang ada dalam album tidak dapat diatur ulang, sehingga penting untuk menyetel posisi item saat ditambahkan.

Awal album

Item media/pengayaan dapat ditambahkan ke awal album sebagai penentuan posisi absolut.

Akhir album

Item media/pemkayaan dapat ditambahkan ke akhir album sebagai penentuan posisi absolut.

Relatif terhadap item media

Item media/pemkayaan dapat ditambahkan secara relatif terhadap item media yang dimulai setelah posisinya di album.

Relatif terhadap item pengaya

Item media/pengayaan dapat ditambahkan secara relatif terhadap item pengayaan yang dimulai setelah posisinya di album.

Menambahkan pengayaan ke album

Pengayaan ditambahkan satu per satu dan harus ditambahkan ke posisi dalam album. Untuk menambahkan pengayaan ke album, panggil albums.addEnrichment.

Jika permintaan berhasil, kode akan menampilkan id item pengayaan, yang dapat digunakan untuk memosisikan item media atau pengayaan lainnya.

REST

Berikut adalah permintaan POST:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment
Content-type: application/json
Authorization: Bearer oauth2-token
request-body

Isi permintaan terdiri dari item pengaya dan posisinya:

{
  "newEnrichmentItem": {
    enrichment-to-be-added
  },
  "albumPosition": {
    position-of-enrichment
}

Berikut adalah contoh respons:

{
  "enrichmentItem": {
    "id": "enrichment-item-id",
  }
}

Java

try {
  // Create the enrichment using the NewEnrichmentItemFactory helper
  NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createTextEnrichment("");

  // Set the position of the enrichment within the album
  AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

  // To add an enrichment, specify the album, the enrichment item,
  // and the position in the album where the enrichment is to be added
  AddEnrichmentToAlbumResponse response = photosLibraryClient
      .addEnrichmentToAlbum(albumId, newEnrichmentItem, albumPosition);
  // The response contains an EnrichmentItem
  // whose ID can be used to position media items or other enrichments
  EnrichmentItem enrichmentItem = response.getEnrichmentItem();
  String itemId = enrichmentItem.getId();
} catch (ApiException e) {
  // Handle error
}

PHP

// Create the enrichment item using the PhotosLibraryResourceFactory helper
$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("");
// ...
// Set the position of the enrichment within the album
$position = new AlbumPosition();
// ...
try {
    // To add an enrichment, specify the album, the enrichment item,
    // and the position in the album where the enrichment is to be added
    $response = $photosLibraryClient->addEnrichmentToAlbum($albumId, $newEnrichmentItem, $position);
    // The response contains an EnrichmentItem
    // whose ID can be used to position media items or other enrichments
    $enrichmentItem = $response->getEnrichmentItem();
    $itemId = $enrichmentItem->getId();

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Pengayaan yang didukung

Pengayaan teks

Pengayaan teks berisi satu string teks (tidak lebih dari 1.000 karakter), seperti yang ditunjukkan pada contoh berikut:

REST

{
  "text": "Text to be shown"
}

Java

// Use the NewEnrichmentItemFactory helper to create a text enrichment item
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createTextEnrichment("text to be shown");

PHP

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("text to be shown");

Pengayaan lokasi

Pengayaan lokasi terdiri dari nama lokasi arbitrer serta posisi lintang dan bujur. locationName dibatasi hingga 500 karakter.

REST

{
  "location": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  }
}

Java

// Use the NewEnrichmentItemFactory helper to create a location enrichment
// with the name, latitude, and longitude of the location
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createLocationEnrichment("Australia", -21.197, 95.821);

PHP

// Create a new location object and set the name, latitude, and longitude of the location
$newLocation = new Location();
$newLocation->setLocationName("Australia");
$newLocation->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithLocation($newLocation);

Pengayaan peta

Pengayaan peta menampilkan dua lokasi, masing-masing yang terdiri dari nama serta lintang dan bujur. Serupa dengan pengayaan lokasi, locationName dalam origin dan destination dibatasi hingga 500 karakter.

REST

{
  "origin": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  },
  "destination": {
    "locationName": "San Francisco",
    "latlng": {
      "latitude": "37.757",
      "longitude": "122.507"
    }
  }
}

Java

// Use the NewEnrichmentItemFactory helper to create a map enrichment item for
// an origin and a destination location
NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createMapEnrichment(
    "Australia", -21.197, 95.821, // origin
    "San Francisco", 37.757, 122.507 // destination
);

PHP

// Create two new location objects to create a map enrichment item
// for an origin and a destination location
$locationAustralia = new Location();
$locationAustralia->setLocationName("Australia");
$locationAustralia->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));

$locationSanFrancisco = new Location();
$locationSanFrancisco->setLocationName("San Francisco");
$locationSanFrancisco->setLatlng((new LatLng())->setLatitude(37.757)->setLongitude(122.507));

$newEnrichmentItem =
  PhotosLibraryResourceFactory::newEnrichmentItemWithMap($locationAustralia, $locationSanFrancisco);

Pemosisian yang didukung

Awal album

Posisi FIRST_IN_ALBUM mengacu pada awal album. Item yang terletak di sini ditampilkan kepada pengguna terlebih dahulu:

REST

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);

Akhir album

Posisi LAST_IN_ALBUM mengacu pada akhir album. Item yang terletak di sini ditampilkan kepada pengguna terakhir.

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::LAST_IN_ALBUM);

Relatif terhadap item media

Menentukan posisi relativeMediaItem mengacu pada posisi relatif terhadap item media. Item ditambahkan setelah item media yang ditentukan.

REST

{
  "position": "after-media-item",
  "relativeMediaItemId": "media-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);

Relatif terhadap item pengaya

Menentukan relativeEnrichmentItemId mengacu pada posisi yang relatif terhadap item pengayaan. Item ditambahkan setelah item pengayaan yang ditentukan.

REST

{
  "position": "after-enrichment-item",
  "relativeEnrichmentItemId": "enrichment-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);

Memodifikasi pengayaan

Saat ini, belum ada cara untuk mengubah pengaya. Namun, setelah pengaya dibuat dan ditambahkan ke album, pengguna dapat mengubah pengaya melalui aplikasi Google Foto.