地點相片 (新)

選取平台： Android iOS Web 服務

您可以使用「Place Photos (新版)」功能，在應用程式中加入高品質的相片內容。您可以透過「地點相片」服務，存取數百萬張儲存在地點資料庫中的相片。Place Photos 會傳回點陣圖片的 URI。位圖圖片的大小上限為 4800 x 4800 像素。

注意： Place 相片 (新版) 適用於 Places SDK for Android 3.4.0 以上版本。詳情請參閱「選擇 SDK 版本」一文。如要進一步瞭解如何使用在 4.0.0 版中新增的 Kotlin API，請參閱參考總覽。

Place Photos 要求

如要擷取地點的圖片，請按照下列步驟操作：

1. 使用 Place Details (新版) 搭配 fetchPlace() 擷取 Place 物件。請務必在回應 Place 物件中加入的欄位清單中加入 Place.Field PHOTO_METADATAS 欄位。
2. 在 FetchPlaceResponse 的 OnSuccessListener 中，呼叫 Place.getPhotoMetadas() 即可從回應 Place 物件中取得 PhotoMetadata 類型的相片中繼資料物件。
3. 建立 FetchResolvedPhotoUriRequest 物件，以便提出要求並傳遞相片中繼資料物件，以及最大高度、最大寬度或兩者的值。
4. 使用 PlacesClient.fetchResolvedPhotoUri() 要求相片 URI。
5. 新增 OnSuccessListener，並從 FetchResolvedPhotoUriResponse 物件取得相片 URI。

注意：如要進一步瞭解如何初始化 PlacesClient，請參閱「初始化 Places API 用戶端」。

您可以使用 CancellationToken，嘗試取消對任何要求類別 (例如 FetchPlaceRequest) 的請求。系統會盡力取消。提出取消要求後，系統不會回覆。發出取消權杖並非保證特定要求會取消，而且即使沒有傳回回應，您仍可能會因要求而遭到收費。

必要參數

FetchResolvedPhotoUriRequest 的必要參數如下：

• 相片中繼資料

  要傳回的照片中繼資料物件。

• 高度或寬度上限

  指定要傳回的圖片最大高度和寬度 (以像素為單位)。如果圖片小於指定的值，系統會傳回原始圖片。如果圖片的任何一邊尺寸較大，系統會將圖片縮放至兩個尺寸中較小的尺寸，並限制為原始顯示比例。最大高度和最大寬度屬性都接受介於 1 到 4800 之間的整數。您必須指定高度和/或寬度上限。

  • 如要設定最大高度參數，請在建構 FetchResolvedPhotoUriRequest 物件時呼叫 setMaxHeight() 方法。
  • 如要設定最大寬度參數，請在建構 FetchResolvedPhotoUriRequest 物件時呼叫 setMaxWidth() 方法。

Place Photos 範例

以下範例說明如何取得地點相片 URI。

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify fields. Requests for photos must always have the PHOTO_METADATAS field.
final List<Place.Field> fields = Collections.singletonList(Place.Field.PHOTO_METADATAS);

// Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace())
final FetchPlaceRequest placeRequest = FetchPlaceRequest.newInstance(placeId, fields);

placesClient.fetchPlace(placeRequest).addOnSuccessListener((response) -> {
    final Place place = response.getPlace();

    // Get the photo metadata.
    final List<PhotoMetadata> metadata = place.getPhotoMetadatas();
    if (metadata == null || metadata.isEmpty()) {
        Log.w(TAG, "No photo metadata.");
        return;
    }
    final PhotoMetadata photoMetadata = metadata.get(0);

    // Get the attribution text and author attributions.
    final String attributions = photoMetadata.getAttributions();
    final AuthorAttributions authorAttributions = photoMetadata.getAuthorAttributions();

    // Create a FetchResolvedPhotoUriRequest.
    final FetchResolvedPhotoUriRequest photoRequest = FetchResolvedPhotoUriRequest.builder(photoMetadata)
        .setMaxWidth(500)
        .setMaxHeight(300)
        .build();

    // Request the photo URI
    placesClient.fetchResolvedPhotoUri(photoRequest).addOnSuccessListener((fetchResolvedPhotoUriResponse) -> {
        Uri uri = fetchResolvedPhotoUriResponse.getUri();
        RequestOptions requestOptions = new RequestOptions().override(Target.SIZE_ORIGINAL);
        Glide.with(this).load(uri).apply(requestOptions).into(imageView);
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            final ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + exception.getMessage());
            final int statusCode = apiException.getStatusCode();
            // TODO: Handle error with given status code.
        }
    });
});

歸因

在大多數情況下，使用地點相片時可以不包含作者資訊，圖片本身也可能已加入必要的作者資訊。不過，類型為 PhotoMetadata 的相片中繼資料物件，可以包含下列兩種額外歸屬資訊：

• 出處：由 PhotoMetadata.getAttributions() 存取的出處字串。
• AuthorAttributions，由 PhotoMetadata.getAuthorAttributions() 存取的 AuthorAttributions 物件。

如果傳回的 PhotoMetadata 物件包含任一種出處資訊，您每次顯示圖片時就必須在應用程式中加入出處資訊。詳情請參閱「顯示出處」。