您可以使用 Places SDK for Android 要求要在應用程式中顯示的地點相片。相片服務傳回的相片取自各種來源,包括業主和使用者提供的相片。
選擇相片格式
Places SDK for Android 支援兩種格式的相片要求:
- 所有 Places SDK for Android 版本:傳回點陣圖圖片。點陣圖圖片的尺寸上限為 1600 x 1600 像素。
- Places SDK for Android (New) 3.4 以上版本:傳回點陣圖圖片的 URI。點陣圖圖片的尺寸上限為 4800 x 4800 像素。
相片擷取程序
如要擷取地點圖片,請按照下列步驟操作:
- 使用 Place Details 擷取
Place
物件 (使用fetchPlace()
或findCurrentPlace()
)。請務必在欄位清單中加入Place.Field PHOTO_METADATAS
欄位,以便納入回應Place
物件。 - 在
FetchPlaceResponse
或FindCurrentPlaceResponse
的OnSuccessListener
中:- 使用
Place.getPhotoMetadas()
從回應Place
物件中取得PhotoMetadata
類型的相片中繼資料物件。 - 如何取得點陣圖圖片:
- 建立
FetchPhotoRequest
物件,並視需要指定高度和寬度上限 (以像素為單位)。相片的寬度或高度上限為 1600 像素。 - 使用
PlacesClient.fetchPhoto()
要求相片點陣圖。 - 新增
OnSuccessListener
並從FetchPhotoResponse
取得相片。
- 建立
- 如要取得相片 URI:
- 建立
FetchResolvedPhotoUriRequest
物件來提出要求。相片的寬度或高度上限為 4800 像素。 - 使用
PlacesClient.fetchResolvedPhotoUri()
要求相片 URI。 - 新增
OnSuccessListener
並從FetchResolvedPhotoUriResponse
物件取得相片 URI。
- 建立
- 使用
存取 3.3.0 以上版本中新增的 PhotoMetadata 資料
Places SDK for Android (新版) 會將 AuthorAttributions
欄位新增至 PhotoMetadata
類別。如果應用程式啟用新 SDK,則 Place.getPhotoMetadas()
傳回的 PhotoMetadata
物件可能包含一或多個作者屬性。
如果 PhotoMetadata
物件包含任何作者資訊 (3.3.0 版中新增的新作者作者資訊,或是 3.2.0 以下版本提供的現有作者資訊),則必須在相片中顯示相關資訊。如要進一步瞭解如何處理所有類型的歸因作業,請參閱「歸因」。
如要將作者姓名填入 PhotoMetadata
物件,您必須:
- 在設定 Google Cloud 專案時啟用新的 SDK。
- 在活動或片段中初始化新的 SDK。
- 在地點詳細資料要求的欄位清單中加入
Place.Field.PHOTO_METADATAS
。 - 呼叫
PlacesClient.fetchPlace()
取得Place
物件,並呼叫Place.getPhotoMetadas()
來取得PhotoMetadata
物件。PlacesClient.findCurrentPlace()
不支援作者姓名欄位。 - 使用
PhotoMetadata.getAuthorAttributions()
取得作者姓名標示。
取得相片
本節說明如何以點陣圖或 URI 格式擷取相片。
取得地點相片做為點陣圖
下例示範如何取得地點相片做為點陣圖。
Kotlin
// Define a Place ID. val placeId = "INSERT_PLACE_ID_HERE" // Specify fields. Requests for photos must always have the PHOTO_METADATAS field. val fields = listOf(Place.Field.PHOTO_METADATAS) // Get a Place object (this example uses fetchPlace(), but you can also use findCurrentPlace()) val placeRequest = FetchPlaceRequest.newInstance(placeId, fields) placesClient.fetchPlace(placeRequest) .addOnSuccessListener { response: FetchPlaceResponse -> val place = response.place // Get the photo metadata. val metada = place.photoMetadatas if (metada == null || metada.isEmpty()) { Log.w(TAG, "No photo metadata.") return@addOnSuccessListener } val photoMetadata = metada.first() // Get the attribution text. val attributions = photoMetadata?.attributions // Create a FetchPhotoRequest. val photoRequest = FetchPhotoRequest.builder(photoMetadata) .setMaxWidth(500) // Optional. .setMaxHeight(300) // Optional. .build() placesClient.fetchPhoto(photoRequest) .addOnSuccessListener { fetchPhotoResponse: FetchPhotoResponse -> val bitmap = fetchPhotoResponse.bitmap imageView.setImageBitmap(bitmap) }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { Log.e(TAG, "Place not found: " + exception.message) val statusCode = exception.statusCode TODO("Handle error with given status code.") } } }
Java
// 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. final String attributions = photoMetadata.getAttributions(); // Create a FetchPhotoRequest. final FetchPhotoRequest photoRequest = FetchPhotoRequest.builder(photoMetadata) .setMaxWidth(500) // Optional. .setMaxHeight(300) // Optional. .build(); placesClient.fetchPhoto(photoRequest).addOnSuccessListener((fetchPhotoResponse) -> { Bitmap bitmap = fetchPhotoResponse.getBitmap(); imageView.setImageBitmap(bitmap); }).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. } }); });
取得地點相片 URI
下例示範如何取得地點相片 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. final String attributions = photoMetadata.getAttributions(); // Create a FetchResolvedPhotoUriRequest. final FetchResolvedPhotoUriRequest photoRequest = FetchResolvedPhotoUriRequest.builder(photoMetadata) .setMaxWidth(500) // Optional. .setMaxHeight(300) // Optional. .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
類型的相片中繼資料物件可包含下列兩種其他作者資訊:
- Attributions:由
PhotoMetadata.getAttributions()
存取的歸因字串。 - AuthorAttributions,是由
PhotoMetadata.getAuthorAttributions()
存取的AuthorAttributions
物件。
如果傳回的 PhotoMetadata
物件包含上述任一作者資訊,則無論如何,您都必須在應用程式中加入作者資訊。如需更多資訊,請參閱「顯示作者資訊」。
用量與計費
呼叫 fetchPhoto()
時,系統會視為「地點相片」SKU 來計費。詳情請參閱「用量與計費」頁面。