تمت ترجمة هذه الصفحة بواسطة 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=&key=YOUR_API_KEY&signature=

أو على النحو التالي:

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

إعادة تحميل معرّفات الصور البانورامية المحذوفة

إذا حاولت استرداد معرّف بانوراما والحصول على ZERO_RESULTS أو لا قيمة، يعني ذلك أنّه قد تم حذف معرّف البانوراما ويجب تحديثه.

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

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

يمكنك تضمين المَعلمات التالية في طلب البيانات الوصفية: 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"`	يشير إلى عدم إمكانية العثور على صورة بانورامية بالقرب من الموقع المقدم. يمكن أن تحدث هذه الاستجابة في حال تقديم معرّف بانوراما غير موجود أو غير صالح. يمكنك الاطّلاع على [تحديث معرّفات البانوراما المحذوفة](#refresh-pano).
`"NOT_FOUND"`	تشير هذه السمة إلى تعذُّر العثور على سلسلة العنوان المقدَّمة في المَعلمة `location`. قد تظهر هذه الرسالة في حال تقديم عنوان غير متوفّر.
`"OVER_QUERY_LIMIT"`	يشير إلى أنّك تجاوزت الحصة اليومية أو الحصة لكل ثانية لواجهة برمجة التطبيقات هذه.
`"REQUEST_DENIED"`	يشير إلى أنّه تم رفض طلبك. قد تظهر هذه الرسالة في حال عدم تفويض طلبك، أو في حال عدم تفعيل واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي" في مشروع Google Cloud Console الذي يحتوي على مفتاح واجهة برمجة التطبيقات الخاص بك.
`"INVALID_REQUEST"`	يشير ذلك بشكل عام إلى أنّ معلَمات طلب البحث (العنوان أو إحداثيات خط العرض وخط الطول أو المكونات) غير متوفّرة.
`"UNKNOWN_ERROR"`	تشير هذه السمة إلى تعذُّر معالجة الطلب بسبب حدوث خطأ في الخادم. غالبًا ما تكون هذه المشكلة مؤقتة. قد ينجح الطلب إذا أعدت المحاولة.

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

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