افزودن غنی‌سازی‌ها

غنی‌سازی‌ها به برنامه شما اجازه می‌دهد ساختار و ارائه عکس‌ها را در آلبومی در Google Photos کنترل کند. این ویژگی به شما امکان می‌دهد تا بافت بیشتری را ازطریق حاشیه‌نویسی‌های نوشتاری یا مکانی به کاربر ارائه دهید و تصاویر را به‌گونه‌ای سفارش دهید/ گروه‌بندی کنید که باهم داستانی را روایت کنند.

محدوده مجوز لازم است

برای افزودن غنی‌سازی، حداقل یکی از دامنه‌های زیر لازم است:

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

برای هر گستره، فراخوانی enrichAlbum فقط به آلبوم‌های ایجادشده توسط برنامه محدود می‌شود.

هنگام استفاده از دامنه .sharing، enrichAlbum به شرایطی محدود می‌شود که توسعه‌دهنده ازطرف مالک آلبوم مشترک اقدام می‌کند.

انواع غنی‌سازی

Google Photos از سه نوع غنی‌سازی در آلبوم‌ها پشتیبانی می‌کند: نوشتار، مکان، و نقشه.

غنی‌سازی نوشتار

غنی‌سازی نوشتاری رشته‌ای از نوشتار ساده است که می‌تواند برای حاشیه‌نویسی آلبوم درج شود.

نماگرفتی از غنی‌سازی نوشتار که در Google Photos نشان داده شده است

غنی‌سازی‌های مکان

غنی‌سازی مکان نشانگر و نام مکانی است که می‌توان برای حاشیه‌نویسی مکان درج کرد.

نماگرفت غنی‌سازی مکان نشان‌داده‌شده در Google Photos

غنی‌سازی‌های نقشه

غنی‌سازی نقشه، نقشه‌ای با مبدأ و مقصد مشخص است که می‌توان آن را در آلبوم درج کرد.

نماگرفتی از غنی‌سازی نقشه که در Google Photos نشان داده شده است

موقعیت‌ها

برای درج کردن فایل‌های رسانه‌ای و غنی‌سازی‌های آلبوم، موقعیت آلبوم را مشخص کنید. موقعیت برای موارد رسانه‌ای اختیاری است، اما باید برای غنی‌سازی آلبوم مشخص شود.

موقعیت را فقط هنگام ایجاد فایل رسانه‌ای یا افزودن غنی‌سازی‌ها می‌توان مشخص کرد. فایل‌های رسانه‌ای موجود در آلبوم را نمی‌توان دوباره سازمان‌دهی کرد، بنابراین مهم است که موقعیت فایل را هنگام اضافه شدن تنظیم کنید.

شروع آلبوم

یک مورد رسانه/غنی‌سازی می‌تواند به ابتدای آلبوم به‌عنوان موقعیت مطلق اضافه شود.

پایان آلبوم

مورد غنی‌سازی/رسانه را می‌توان به‌عنوان موقعیت مطلق به انتهای آلبوم اضافه کرد.

نسبت به فایل رسانه‌ای

یک مورد رسانه‌ای/غنی‌سازی می‌تواند نسبت به یک مورد رسانه‌ای که پس‌از موقعیت آن در آلبوم شروع می‌شود، اضافه شود.

نسبت به مورد غنی‌سازی

مورد رسانه/غنی‌سازی را می‌توان نسبت به شروع مورد غنی‌سازی بعداز جایگاه آن در آلبوم اضافه کرد.

درحال افزودن غنی‌سازی به آلبوم

غنی‌سازی‌ها یکی‌یکی اضافه می‌شوند و باید به موقعیتی در آلبوم اضافه شوند. برای افزودن غنی‌سازی به آلبوم، albums.addEnrichment را فراخوانی کنید.

اگر درخواست موفقیت‌آمیز باشد، id مورد غنی‌سازی را برمی‌گرداند که می‌توان از آن برای جای‌گذاری موارد رسانه‌ای یا غنی‌سازی‌های دیگر استفاده کرد.

استراحت

در اینجا یک درخواست POST آورده شده است:

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

بدنه درخواست شامل مورد غنی‌سازی و موقعیت آن است:

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

در اینجا یک پاسخ نمونه آورده شده است:

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

جاوا

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
}

غنی‌سازی‌های پشتیبانی‌شده

غنی‌سازی نوشتار

غنی‌سازی‌های نوشتاری حاوی یک رشته نوشتاری (نه بیشتر از ۱۰۰۰ نویسه) هستند، همان‌طور که در مثال زیر نشان داده شده است:

استراحت

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

جاوا

// 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");

غنی‌سازی‌های مکان

غنی‌سازی‌های مکان شامل نام مکان دلخواه و موقعیت عرض جغرافیایی و طول جغرافیایی است. locationName به ۵۰۰ نویسه محدود است.

استراحت

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

جاوا

// 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);

غنی‌سازی‌های نقشه

غنی‌سازی‌های نقشه دو مکان را نشان می‌دهد که هرکدام شامل نام و طول و عرض جغرافیایی است. مشابه غنی‌سازی مکان، locationName در مبدأ و destination به ۵۰۰ نویسه محدود است.

استراحت

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

جاوا

// 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);

جایگاه‌سازی پشتیبانی‌شده

شروع آلبوم

موقعیت FIRST_IN_ALBUM به شروع آلبوم اشاره دارد. مواردی که در اینجا قرار دارند ابتدا به کاربر نشان داده می‌شوند:

استراحت

{
  "position": "FIRST_IN_ALBUM",
}

جاوا

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

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

پایان آلبوم

موقعیت LAST_IN_ALBUM به انتهای آلبوم اشاره دارد. مواردی که اینجا قرار دارند در آخر به کاربر نشان داده می‌شوند.

استراحت

{
  "position": "LAST_IN_ALBUM",
}

جاوا

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

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

نسبت به فایل رسانه‌ای

مشخص کردن موقعیت relativeMediaItem به موقعیتی نسبت‌به فایل رسانه‌ای اشاره دارد. موارد پس‌از فایل رسانه‌ای مشخص‌شده اضافه می‌شوند.

استراحت

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

جاوا

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

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

نسبت به مورد غنی‌سازی

مشخص کردن relativeEnrichmentItemId به موقعیتی نسبت به مورد غنی‌سازی اشاره دارد. موارد پس‌از مورد غنی‌سازی مشخص‌شده اضافه می‌شوند.

استراحت

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

جاوا

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

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

درحال اصلاح غنی‌سازی‌ها

درحال‌حاضر، راهی برای اصلاح غنی‌سازی‌ها وجود ندارد. بااین‌حال، وقتی غنی‌سازی ایجاد شد و به آلبوم اضافه شد، کاربر می‌تواند غنی‌سازی‌ها را ازطریق برنامه Google Photos اصلاح کند.