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

البيانات الوصفية لصور "التجوّل الافتراضي"

المقدمة

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

تتوفّر طلبات البيانات الوصفية لواجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي" بدون أي رسوم. لا يتم استهلاك أي حصة عند طلب البيانات الوصفية. يتم استهلاك الحصة فقط عند تحميل صورة باستخدام واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي".

عند إجراء طلبات البيانات الوصفية لصور التجوّل الافتراضي، تكون صور بانوراما دقيقة لـ 50 مترًا.

الوصول إلى البيانات الوصفية للصور

طلب البيانات الوصفية لصورة التجوّل الافتراضي هو عنوان URL بتنسيق HTTP على النحو التالي:

https://maps.googleapis.com/maps/api/streetview/metadata?parameters

وكما هو معتاد في عناوين URL، يتم فصل جميع المعلمات باستخدام رمز العطف اللاتيني (&).

المعلمات المطلوبة لطلبات البيانات الوصفية

تقبل طلبات البيانات الوصفية معلمات عناوين URL نفسها مثل طلبات صور واجهة برمجة التطبيقات الثابتة للتجوّل الافتراضي، على الرغم من أن المَعلمات التالية مطلوبة فقط:

يمكنك تنفيذ أحد الإجراءين التاليين:

location — يمكن أن يكون سلسلة نصية (مثل Chagrin Falls, OH) أو زوجًا من إحداثيات خطوط العرض/الطول مفصولة بفواصل (40.457375,-80.009353).

أو الصيغة التالية:

pano — رقم تعريف بانورامي محدد. وتكون هذه الصور ثابتة بشكل عام، إلا أن الصور البانورامية قد تغيّر رقم التعريف بمرور الوقت حيث يتم تحديث الصور.

بالإضافة إلى:

key وsignature — مفتاح واجهة برمجة التطبيقات مطلوب لمصادقة الطلب. يكون التوقيع الرقمي مطلوبًا أيضًا في بعض الحالات، ويُنصح به دائمًا. لمزيد من المعلومات، يمكنك الاطّلاع على الحصول على مفتاح وتوقيع.

سيبدو طلب البيانات الوصفية الذي يحتوي على معلمات مطلوبة على النحو التالي:

https://maps.googleapis.com/maps/api/streetview/metadata?location=<STRING>&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

أو هكذا:

https://maps.googleapis.com/maps/api/streetview/metadata?pano=<STRING>&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

معلمات اختيارية لطلبات البيانات الوصفية

يمكنك تضمين المعلّمات التالية في طلب البيانات الوصفية: size heading وfov وpitch. لاحظ أن هذه المعلمات لا تؤثر على البيانات المتعلقة بصور البانوراما، أو أيها. تسمح واجهة برمجة التطبيقات بتضمين المعلمات نفسها الموجودة في طلب الصور لتسهيل إنشاء طلب بيانات وصفية ذات صلة بطلب صور معين، ولكن بالنسبة إلى طلبات البيانات الوصفية، تتجاهل واجهة برمجة التطبيقات المعلمات الاختيارية وقيمها. اطّلع على دليل مطوّري البرامج لواجهة برمجة التطبيقات للتجوّل الافتراضي للحصول على معلومات حول استخدام هذه المَعلمات.

تنسيق الاستجابة

يتم عرض استجابات البيانات الوصفية بتنسيق JSON فقط.

أمثلة

المثال 1: تم العثور على بانوراما

تطلب عناوين URL التالية بنجاح البيانات الوصفية والصورة للصورة البانورامية نفسها.

طلب البيانات الوصفية والرد عليها

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "copyright" : "© 2017 Google",
   "date" : "2016-05",
   "location" : {
      "lat" : 48.85783227207914,
      "lng" : 2.295226175151347
   },
   "pano_id" : "tu510ie_z4ptBZYo2BGEJg",
   "status" : "OK"
}

طلب الصور والرد عليها، حيث من المتوقع ظهور الصورة المفقودة.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

المثال 2: لم يتم العثور على البانوراما

تتطلب عناوين URL التالية بيانات وصفية وصورة للبانوراما التي تعذر العثور عليها في الموقع المحدد أو بالقرب منه.

طلب البيانات الوصفية والرد عليها

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "status" : "ZERO_RESULTS"
}

طلب الصور والرد عليها

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

رموز الحالة

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

الحالة	الوصف
`"OK"`	يشير إلى عدم حدوث أخطاء؛ حيث تم العثور على صورة بانورامية ويتم عرض البيانات الوصفية.
`"ZERO_RESULTS"`	تشير إلى أنه لا يمكن العثور على أي بانوراما بالقرب من الموقع المقدم. وقد يحدث هذا إذا تم تقديم رقم تعريف بانوراما غير صالح أو غير موجود.
`"NOT_FOUND"`	تشير هذه الخاصية إلى أنه تعذّر العثور على سلسلة العنوان المقدّمة في المعلَمة `location`. قد يحدث هذا إذا تم تقديم عنوان غير موجود.
`"OVER_QUERY_LIMIT"`	للإشارة إلى أنك تجاوزت حصتك اليومية أو حصة الثانية لكل واجهة برمجة تطبيقات.
`"REQUEST_DENIED"`	تشير هذه الحالة إلى أنه تم رفض طلبك. وقد يحدث هذا إذا لم تفوّض طلبك، أو إذا لم يتم تفعيل واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي" في مشروع Google Cloud Console الذي يحتوي على مفتاح واجهة برمجة التطبيقات الخاص بك.
`"INVALID_REQUEST"`	يشير ذلك بشكل عام إلى أنّ معلَمات طلب البحث (العنوان أو خط العرض أو المكوّنات) غير متوفّرة.
`"UNKNOWN_ERROR"`	تشير إلى أنّه تعذّرت معالجة الطلب بسبب خطأ في الخادم. وغالبًا ما تكون هذه حالة مؤقتة. قد ينجح الطلب في حال إعادة المحاولة.

مزيد من المعلومات

لمزيد من المعلومات حول استخدام واجهة برمجة التطبيقات الثابتة للتجوّل الافتراضي أو غيرها من منتجات واجهة برمجة التطبيقات لخرائط Google، تأكد من الرجوع إلى صفحة الدعم لواجهة برمجة تطبيقات الخرائط.