صور المكان

اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب

يمكنك استخدام حزمة تطوير برامج الأماكن لأجهزة Android لطلب عرض صورة مكان في تطبيقك. تأتي الصور التي تعرضها خدمة الصور من مجموعة متنوعة من المصادر، بما في ذلك مالكي الأنشطة التجارية والصور التي ساهم بها المستخدمون.

اختيار تنسيق الصورة

تتوافق حزمة تطوير برامج الأماكن لأجهزة Android مع تنسيقين للصورة المطلوبة:

  • جميع إصدارات حزمة تطوير البرامج للأماكن المخصّصة لنظام التشغيل Android: تعرض الصورة النقطية. ويبلغ الحد الأقصى لحجم الصورة النقطية 1600 × 1600 بكسل.
  • حزمة تطوير البرامج (SDK) لأماكن Google لنظام التشغيل Android (الجديدة) الإصدار 3.4 والإصدارات الأحدث: تعرض معرّف الموارد المنتظم (URI) للصورة النقطية. يبلغ الحد الأقصى لحجم صورة الصورة النقطية 4800 × 4800 بكسل.

عملية استرجاع الصور

لاسترداد صورة لمكان:

  1. استخدِم تفاصيل المكان لاسترجاع عنصر Place (استخدِم إما fetchPlace() أو findCurrentPlace()). احرص على تضمين الحقل Place.Field PHOTO_METADATAS في قائمة الحقول التي سيتم تضمينها في عنصر الاستجابة Place.
  2. في OnSuccessListener الخاصة بـ FetchPlaceResponse أو FindCurrentPlaceResponse:
    1. استخدِم Place.getPhotoMetadas() للحصول على عنصر البيانات الوصفية للصور، من النوع PhotoMetadata من عنصر الاستجابة Place.
    2. للحصول على صورة نقطية:
      1. أنشِئ عنصر FetchPhotoRequest، مع تحديد الحد الأقصى للارتفاع والعرض اختياريًا (بالبكسل). ويمكن أن يبلغ الحد الأقصى للعرض أو الارتفاع 1600 بكسل.
      2. استخدِم الرمز PlacesClient.fetchPhoto() لطلب الصورة النقطية.
      3. أضِف OnSuccessListener واحصل على الصورة من خلال FetchPhotoResponse.
    3. للحصول على معرّف الموارد المنتظم (URI) للصورة:
      1. أنشِئ عنصر FetchResolvedPhotoUriRequest لتقديم الطلب. يمكن أن يبلغ الحد الأقصى للعرض أو الارتفاع 4800 بكسل.
      2. استخدِم PlacesClient.fetchResolvedPhotoUri() لطلب معرّف الموارد المنتظم (URI) للصورة.
      3. أضِف OnSuccessListener واحصل على معرّف الموارد المنتظم (URI) للصورة من الكائن FetchResolvedPhotoUriResponse.

الوصول إلى بيانات PhotoMetadata التي تمت إضافتها في الإصدار 3.3.0 والإصدارات الأحدث

تضيف حزمة تطوير برامج الأماكن لأجهزة Android (جديدة) الحقل AuthorAttributions إلى فئة PhotoMetadata. إذا فعّل تطبيقك حزمة تطوير البرامج (SDK) الجديدة، يمكن أن يحتوي عنصر PhotoMetadata الذي يعرضه Place.getPhotoMetadas() على إحالة مؤلف واحدة أو أكثر.

عندما يحتوي العنصر PhotoMetadata على أي أسماء المساهمين، سواء كانت معلومات المؤلفين الجديدة التي تمت إضافتها في الإصدار 3.3.0 أو تلك المتوفرة في الإصدار 3.2.0 والإصدارات الأقدم، يجب عرضها مع الصورة. لمزيد من المعلومات حول معالجة جميع أنواع الإحالة، اطّلع على عمليات تحديد المصدر.

لتعبئة الكائن PhotoMetadata بسمات المؤلف، يجب إجراء ما يلي:

  1. عليك تفعيل حزمة تطوير البرامج (SDK) الجديدة عند إعداد مشروعك على Google Cloud.
  2. إعداد حزمة تطوير البرامج (SDK) الجديدة ضمن نشاط أو جزء
  3. أدرِج Place.Field.PHOTO_METADATAS في قائمة الحقول الخاصة بطلب تفاصيل المكان.
  4. اطلب العنصر PlacesClient.fetchPlace() للحصول على العنصر Place واطلب الرمز Place.getPhotoMetadas() للحصول على العنصر PhotoMetadata. حقل أسماء المؤلفين غير متاح في PlacesClient.findCurrentPlace().
  5. استخدِم 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، على أي من نوعَين من عمليات تحديد المصدر الإضافية:

إذا كان عنصر PhotoMetadata المعروض يتضمن أي نوع من أنواع الإحالة، يجب عليك تضمين الإحالة في تطبيقك أينما عرضت الصورة. لمزيد من المعلومات، راجِع عرض عمليات تحديد المصدر.

الاستخدام والفوترة

يتم تحصيل رسوم رمز التخزين التعريفي لصورة الأماكن مقابل المكالمات إلى fetchPhoto(). يمكنك الاطّلاع على صفحة الاستخدام والفوترة للحصول على مزيد من التفاصيل.