تمت ترجمة هذه الصفحة بواسطة 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 API الأخرى، احرص على الاطّلاع على صفحة دعم "خرائط Google".