تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

صورة المكان (جديد)

خدمة Place Photo (جديد) هي واجهة برمجة تطبيقات للقراءة فقط تتيح لك إضافة محتوى تصويري عالية الجودة إلى تطبيقك. تمنحك خدمة "صور المكان" إمكانية الوصول إلى ملايين الصور المخزنة في قاعدة بيانات الأماكن.

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

يتيح لك "مستكشف واجهة برمجة التطبيقات" إجراء طلبات مباشرة لتتمكن من الإلمام بواجهة برمجة التطبيقات وخيارات واجهة برمجة التطبيقات:

جرِّبه الآن

تقديم طلبات الصور

طلب "صورة المكان" هو طلب HTTP GET إلى عنوان URL بالتنسيق التالي:

https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

الأماكن التي تكون فيها المَعلمات التالية مطلوبة:

يحتوي NAME على اسم مورد الصورة.
يحتوي API_KEY على مفتاح واجهة برمجة التطبيقات.
تحتوي السمة PARAMETERS على المَعلمة maxHeightPx أو المَعلمة maxWidthPx أو كلتيهما.

في ما يلي قائمة كاملة بالمعلَمات المطلوبة والاختيارية.

المعلمات المطلوبة

اسم الصورة

معرّف سلسلة يعرّف الصورة بشكل فريد. يتم عرض أسماء الصور من طلب تفاصيل المكان (جديد) أو بحث عن قرب (جديد) أو بحث نصي (جديد) في السمة name لكل عنصر في مصفوفة photos[].

على سبيل المثال، راجِع الحصول على اسم صورة.

maxheightPx وmax widthPx

تُحدِّد الحد الأقصى لارتفاع الصورة وعرضها بالبكسل. إذا كانت الصورة أصغر من القيم المحددة، فسيتم عرض الصورة الأصلية. إذا كانت الصورة أكبر في أي من البعدين، فسيتم تغيير حجمها لتتناسب مع الأصغر من البُعدين، وتقتصر على نسبة العرض إلى الارتفاع الأصلية. تقبل كلتا الخاصيتَين maxheight وmaxwidth عددًا صحيحًا بين 1 و4,800.

يجب تحديد إما maxHeightPx أو maxWidthPx أو كليهما.

المعلمات الاختيارية

skipHttpRedirect

إذا كانت false (الخيار التلقائي)، عليك إعادة توجيه HTTP إلى الصورة لعرض الصورة. إذا كانت النسخة true، يمكنك تخطّي عملية إعادة التوجيه وعرض استجابة JSON تحتوي على مشاكل الصورة. مثال:

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

ويتم تجاهل هذا الخيار للطلبات التي لا تستخدم HTTP.

الحصول على اسم للصورة

يجب أن تشتمل جميع الطلبات المقدمة إلى خدمة "صورة المكان" على اسم مورد صورة يتم عرضه استجابةً لطلب بحث عن قرب أو بحث نصي أو تفاصيل المكان. يحتوي الرد على هذه الطلبات على مصفوفة photos[] إذا كان المكان يحتوي على محتوى صور فوتوغرافية ذات صلة.

ملاحظة: لتضمين المصفوفة photos[] في الرد، احرص على تضمين photos (تفاصيل المكان) أو places.photos (البحث عن مكان قريب والبحث النصي) في قناع الطلب. يمكن لكل واجهة برمجة تطبيقات عرض ما يصل إلى 10 صور للموقع الجغرافي لأحد الأماكن.

يحتوي كل عنصر من عناصر photo[] على الحقول التالية:

name: سلسلة تحتوي على اسم مورد الصورة عند تنفيذ طلب صورة. وتكون هذه السلسلة بالشكل:
```
places/PLACE_ID/photos/PHOTO_RESOURCE
```
heightPx — الحد الأقصى لارتفاع الصورة بالبكسل.
widthPx - الحد الأقصى لعرض الصورة بالبكسل.
authorAttributions[] - أي عمليات إحالة مطلوبة هذا الحقل موجود دائمًا، ولكنه قد يكون فارغًا.

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

يعرض المثال التالي طلب تفاصيل المكان الذي يتضمن photos في قناع الحقل بحيث يتضمن الرد صفيف photos[] في الاستجابة:

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E

في ما يلي مثال على مصفوفة photos[] في الاستجابة.

    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },    ...

طلب صورة مكان

يعرض نموذج الطلب أدناه صورة باستخدام مورده name، مع تغيير حجمها بحيث لا يزيد طولها وعرضها عن 400 بكسل:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

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

وإذا تجاوز طلبك حصتك المتاحة، يعرض الخادم حالة HTTP 403 وسيعرض الصورة أدناه للإشارة إلى أنّه تم تجاوز الحصة:

إذا لم يتمكن الخادم من فهم طلبك، فسيعرض حالة HTTP 400، التي تشير إلى طلب غير صالح. تشمل الأسباب الأكثر شيوعًا للطلب غير الصالح ما يلي:

لم يتم تحديد اسم الصورة التي تم إرسالها بشكل صحيح.
ولم يتضمن الطلب المعلَمة maxHeightPx أو maxWidthPx.
وقد تم ضبط قيمة maxHeightPx أو المعلَمة maxWidthtPx على null.
انتهت صلاحية name. إذا انتهت صلاحية name، يمكنك تقديم طلب إلى تفاصيل المكان (جديد) أو البحث عن قرب (جديد) أو بحث نصي (جديد) للحصول على name جديد.

تجربة

يتيح لك "مستكشف واجهة برمجة التطبيقات" تقديم طلبات نموذجية حتى تتمكّن من التعرّف على خيارات واجهة برمجة التطبيقات وواجهة برمجة التطبيقات

لتقديم طلب:

انقر على رمز واجهة برمجة التطبيقات على الجانب الأيسر من الصفحة.
يمكنك ضبط المعلَمة name على:
```
places/PLACE_ID/photos/PHOTO_RESOURCE/media
```
ملاحظة: تأكَّد من استخدام name من طلب حديث لعرض تفاصيل المكان، لأنّه يمكن أن تنتهي صلاحية السمة name.
اضبط السمة skipHttpRedirect على true لكي يعرض الطلب استجابة JSON. يعرض الطلب تلقائيًا الصورة التي لا يمكن عرضها من خلال مستكشف واجهة برمجة التطبيقات.
انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهة برمجة التطبيقات"، انقر على رمز التوسيع، ، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".