إضافة معلومات مفصّلة

تسمح التحسينات لتطبيقك بالتحكم في بنية وطريقة عرض من الصور داخل ألبوم في "صور Google". تسمح لك بتقديم المستخدم مع سياق إضافي من خلال التعليقات التوضيحية للنصوص أو المواقع الجغرافية والترتيب/المجموعة والصور التي تروي قصة معًا.

نطاق التفويض المطلوب

لإضافة إضافات، يجب استخدام أحد النطاقات التالية على الأقل:

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

بالنسبة إلى كل نطاق، تقتصر مكالمة enrichAlbum على الألبومات التي تم إنشاؤها فقط. من خلال التطبيق.

عند استخدام نطاق .sharing، يقتصر enrichAlbum على الظروف. حيث يتصرّف مطوّر البرامج نيابةً عن مالك الألبوم المشترَك.

أنواع إثراء البيانات

يدعم تطبيق "صور Google" ثلاثة أنواع من العناصر الإضافية في الألبومات: النصوص والمواقع الجغرافية والخرائط.

إثراء النص

إثراء النص هو سلسلة نصية عادية يمكن إدراجها لإضافة تعليق الألبوم.

لقطة شاشة تُظهر ميزة إثراء النص في "صور Google"

تحسينات الموقع الجغرافي

إثراء الموقع هو علامة واسم المكان الذي يمكن إدراجه لإضافة تعليقات توضيحية إلى أحد المواقع

لقطة شاشة تُظهر ميزة "تحسين الموقع الجغرافي" في "صور Google"

إثراءات الخريطة

إثراء الخريطة هو خريطة ذات أصل ووجهة محددة يمكن تم إدراجها في الألبوم.

لقطة شاشة تُظهر ميزة "تحسين الخريطة" في "صور Google"

المواضع

لإدراج عناصر الوسائط وإثراءات الألبوم، حدِّد موضع الألبوم. يكون الموضع اختياريًا لعناصر الوسائط، ولكن يجب تحديده للألبوم والاستفادة منه.

لا يمكن تحديد موضع الإعلان إلا عندما إنشاء ملف وسائط أو إضافة تحسينات. لا يمكن إعادة تنظيم عناصر الوسائط الحالية في ألبوم، لذا من المهم ضبط موضع العنصر عند إضافته.

بداية الألبوم

يمكن إضافة وسائط/عنصر تحسين إلى بداية الألبوم باعتباره عنصرًا أساسيًا للمكانة في السوق.

نهاية الألبوم

يمكن إضافة وسائط/عنصر تحسين إلى نهاية الألبوم بشكل مطلق للمكانة في السوق.

نسبةً إلى عنصر الوسائط

يمكن إضافة وسائط/عنصر تحسيني بالنسبة إلى عنصر وسائط يبدأ بعد موقعه في الألبوم.

نسبة إلى عنصر التحسين

يمكن إضافة وسائط/عنصر تحسيني بالنسبة إلى عنصر التحسين الذي يبدأ بعد وضعه في الألبوم.

إضافة تحسينات إلى الألبوم

تتم إضافة الإثراء واحدًا تلو الآخر، ويجب إضافتها إلى موضع في ألبوم. لإضافة تحسينات إلى ألبوم ما، يمكنك الاتصال 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",
  }
}

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
}

الإضافات المتوافقة

إثراء النص

تحتوي إثراء النص على سلسلة نصية واحدة (لا تزيد عن 1000 حرف)، كما كما هو موضح في المثال التالي:

راحة

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

تحسينات الموقع الجغرافي

تتكون إضافات الموقع من اسم موقع عشوائي وخط العرض خط الطول. وlocationName هو الحد الأقصى لعدد الأحرف المسموح به وهو 500 حرف.

راحة

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

إثراءات الخريطة

تعرض إضافات الخرائط موقعَين جغرافيَين يتألّف كل منهما من اسم وخط العرض. وخط الطول. وعلى غرار تعزيز الموقع، فإن locationName ضمن تم تحديد قيمة السمة "المصدر" وdestination على 500 حرف.

راحة

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

الموضع المتوافق

بداية الألبوم

يشير الموضع FIRST_IN_ALBUM إلى بداية الألبوم. العناصر التي تم العثور عليها يتم عرضها هنا للمستخدم أولاً:

راحة

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

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

نهاية الألبوم

يشير الموضع LAST_IN_ALBUM إلى نهاية الألبوم. العناصر المتوفرة هنا تظهر للمستخدم أخيرًا.

راحة

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

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

نسبةً إلى عنصر الوسائط

يشير تحديد الموضع relativeMediaItem إلى موضع نسبي ملف وسائط. تتم إضافة العناصر بعد ملف الوسائط المحدّد.

راحة

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

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

نسبة إلى عنصر التحسين

يشير تحديد relativeEnrichmentItemId إلى موضع نسبي العنصر الإضافي. تتم إضافة العناصر بعد عنصر التحسين المحدد.

راحة

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

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

تعديل التحسينات

وفي الوقت الحالي، ليست هناك طريقة لتعديل التحسينات. ومع ذلك، بمجرد إثراء تم إنشاؤها وإضافتها إلى ألبوم، يمكن للمستخدم تعديل الإثراءات من خلال تطبيق "صور Google".