مقدمة
توفّر طلبات البيانات الوصفية الثابتة لواجهة برمجة التطبيقات في ميزة "التجوّل الافتراضي" بيانات عن ميزة "التجوّل الافتراضي" عرض الصور البانورامية. باستخدام البيانات الوصفية، يمكنك معرفة ما إذا كانت صورة "التجوّل الافتراضي" يتوفّر في موقع جغرافي معيّن، بالإضافة إلى إمكانية الحصول على إمكانية وصول آلي إلى إحداثيات خط العرض وخط الطول، ومعرف البانوراما، وتاريخ التقاط الالتقاط ومعلومات حقوق الطبع والنشر الخاصة بالصورة. الوصول إلى هذه البيانات تتيح لك البيانات الوصفية تخصيص سلوك الخطأ في تطبيقك.
تتوفّر طلبات البيانات الوصفية الثابتة لواجهة برمجة التطبيقات في ميزة "التجوّل الافتراضي" بدون أي الشحن. لا يتم استهلاك أي حصة عند طلب البيانات الوصفية. لا يتم استهلاك الحصة إلا عند تحميل صورة باستخدام واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي"
عند تقديم طلبات البيانات الوصفية لصور "التجوّل الافتراضي"، يتم عرض الصور البانورامية دقيق حتى 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" |
تشير بشكل عام إلى أن معاملات طلب البحث (address، أو إحداثيات خطوط الطول والعرض) مفقودة. |
"UNKNOWN_ERROR" |
يشير إلى تعذُّر معالجة الطلب بسبب خطأ في الخادم. وغالبًا ما تكون هذه المشكلة مؤقتة. قد ينجح الطلب في حال إعادة المحاولة. |
مزيد من المعلومات
لمزيد من المعلومات حول استخدام واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي" منتجات API لخرائط Google الأخرى، تأكد من مراجعة واجهة برمجة تطبيقات الخرائط صفحة الدعم.