يتضمن خرائط Azure خدمة البحث واجهة برمجة التطبيقات التي توفر إمكانات مختلفة لمساعدة المطورين على البحث عن العناوين والأماكن وقوائم الأعمال حسب الاسم أو الفئة والمعلومات الجغرافية الأخرى. على سبيل المثال، يسمح Search Fuzzy للمستخدمين بالبحث عن عنوان أو نقطة اهتمام (POI).
تشرح هذه المقالة كيفية تطبيق الممارسات الصوتية عند استدعاء البيانات من خرائط Azure خدمة البحث. ستتعلم كيفية:
يمكنك استخدام أي بيئة تطوير API مثل Postman أو bruno لتشغيل نماذج طلب HTTP الموضحة في هذه المقالة أو لإنشاء استدعاءات REST.
أفضل الممارسات لترميز العناوين جغرافيًا
عند البحث عن عنوان كامل أو جزئي باستخدام خرائط Azure خدمة البحث، تقرأ واجهة برمجة التطبيقات الكلمات الأساسية من استعلام البحث. ثم تقوم بإرجاع إحداثيات خطوط الطول والعرض الخاصة بالعنوان. تسمى هذه العملية التكويد الجغرافي.
تعتمد القدرة على الترميز الجغرافي في بلد/منطقة على توفر بيانات الطريق ودقة خدمة الترميز الجغرافي. لمزيد من المعلومات حول إمكانيات الترميز الجغرافي لخرائط Azure حسب البلد أو المنطقة، راجع تغطية الترميز الجغرافي.
تقييد نتائج البحث
يمكن أن تساعدك واجهة برمجة تطبيقات Azure Maps Search في تقييد نتائج البحث بشكل مناسب. أنت تحد من النتائج بحيث يمكنك عرض البيانات ذات الصلة للمستخدمين.
ملاحظة
تدعم واجهات برمجة تطبيقات البحث معلمات أكثر من تلك التي تناقشها هذه المقالة فقط.
نتائج البحث المتحيزة جغرافيا
للحصول على نتائج جغرافية إلى المنطقة ذات الصلة للمستخدم، أضف دائماً أكبر عدد ممكن من تفاصيل الموقع. قد ترغب في تقييد نتائج البحث عن طريق تحديد بعض أنواع الإدخال:
اضبط المعلمة countrySet. يمكنك ضبطه على US,FR، على سبيل المثال. بشكل افتراضي، تبحث واجهة برمجة التطبيقات في العالم بأسره، لذا يمكنها إرجاع نتائج غير ضرورية. إذا كان طلب البحث لا يحتوي على معلمة countrySet، فقد يعرض البحث نتائج غير دقيقة. على سبيل المثال، يؤدي البحث عن مدينة باسم Bellevue إلى عرض نتائج من الولايات المتحدة الأمريكية وفرنسا لأن كلا البلدين/المنطقتين يحتويان على مدينة باسم Bellevue.
يمكنك استخدام المعلمات btmRight وtopleft لتعيين المربع المحيط. تقصر هذه المعلمات البحث على منطقة معينة على الخريطة.
للتأثير في المنطقة ذات الصلة بالنتائج، حدد معلمات الإحداثيات lat وlon. استخدم المعلمة radius لتعيين نصف قطر منطقة البحث.
معلمات البحث غير واضحة
نوصي باستخدام Search Fuzzy عندما لا تعرف مدخلات المستخدم لاستعلام بحث. على سبيل المثال، يمكن أن يكون الإدخال من المستخدم عنوانًا أو نوع نقطة اهتمام (POI)، مثل مركز تسوق. تجمع واجهة برمجة التطبيقات بين البحث عن نقاط الاهتمام والتشفير الجغرافي في بحث أحادي السطر:
تساعد المعلمات minFuzzyLevel وmaxFuzzyLevel في إرجاع التطابقات ذات الصلة حتى عندما لا تتطابق معامِلات طلب البحث تمامًا مع المعلومات التي يريدها المستخدم. لتحقيق أقصى قدر من الأداء وتقليل النتائج غير المعتادة، قم بتعيين استعلامات البحث على الافتراضيات minFuzzyLevel=1 وmaxFuzzyLevel=2.
على سبيل المثال، عندما يتم تعيين المعلمة maxFuzzyLevel على 2، فإن مصطلح البحث مطعم يطابق مطعم. يمكنك تجاوز مستويات التشويش الافتراضية عندما تحتاج إلى ذلك.
استخدم المعلمة idxSet لتحديد أولويات المجموعة الدقيقة لأنواع النتائج. لتحديد أولويات مجموعة محددة من النتائج، يمكنك إرسال قائمة من الفهارس مفصولة بفواصل. في قائمتك، لا يهم ترتيب العناصر. تدعم خرائط Azure الفهارس التالية:
Addr
-
نطاقات العنوان: نقاط العنوان التي تم إقحامها من بداية الشارع ونهايته. يتم تمثيل هذه النقاط كنطاقات عناوين.
Geo
-
المناطق الجغرافية: التقسيمات الإدارية للأرض. يمكن أن تكون المنطقة الجغرافية دولة/منطقة أو ولاية أو مدينة، على سبيل المثال.
PAD
-
عناوين النقطة: العناوين التي تتضمن اسم الشارع ورقمه. يمكن العثور على عناوين النقاط في فهرس. مثال على ذلك Soquel Dr 2501. يوفر عنوان النقطة أعلى مستوى من الدقة المتاح للعناوين.
POI
-
مجالات الاهتمام: نقاط على الخريطة تستحق الاهتمام أو قد تكون مثيرة للاهتمام.
لا يرجع عنوان البحث واجهات POIs.
Str
-
الشوارع: الشوارع على الخريطة.
XStr
-
اعبر الشوارع أو التقاطعات: التقاطعات أو الأماكن التي يتقاطع فيها شارعان.
أمثلة الاستخدام
idxSet=POI - البحث عن النقاط المهمة فقط.
idxSet=PAD,Addr - عناوين البحث فقط.
PAD يشير إلى عنوان النقطة، ويشير Addr إلى نطاق العنوان.
عكس التكويد الجغرافي والتصفية لنوع كيان جغرافي
عند إجراء بحث في الرمز الجغرافي العكسي باستخدام عكس عنوان البحث، يمكن للخدمة إرجاع مضلعات للمناطق الإدارية. على سبيل المثال، قد ترغب في جلب مضلع المنطقة لمدينة. لتضييق البحث على أنواع كيانات جغرافية معينة، قم بتضمين المعلمة entityType في طلباتك.
تحتوي الاستجابة الناتجة على معرف الموقع الجغرافي ونوع الكيان المطابق. إذا قدمت أكثر من كيان واحد، فإن نقطة النهاية تعرض أصغر كيان متاح. يمكنك استخدام المعرف الهندسي الذي تم إرجاعه للحصول على الشكل الهندسي للجغرافيا من خلال خدمة مضلع البحث.
استخدم المعلمة language لتعيين لغة نتائج البحث التي تم إرجاعها. إذا لم يقم الطلب بتعيين اللغة، فسيستخدم خدمة البحث بشكل افتراضي اللغة الأكثر شيوعا في البلد أو المنطقة. في حالة عدم توفر أي بيانات باللغة المحددة، يتم استخدام اللغة الافتراضية.
للعثور على مزيد من التطابقات لطلبات البحث الجزئية، قم بتعيين المعامل typeahead على true. يتم تفسير هذا الاستعلام على أنه إدخال جزئي، ويدخل البحث في الوضع التنبئي. إذا لم تقم بتعيين المعلمة typeahead على true، فستفترض الخدمة أن جميع المعلومات ذات الصلة قد تم تمريرها.
في نموذج الاستعلام التالي، يتم الاستعلام عن خدمة عنوان البحث ل Microsoft. هنا، تم تعيين المعلمة typeahead على true. يوضح الرد أن خدمة البحث فسرت الاستعلام على أنه استعلام جزئي. تحتوي الاستجابة على نتائج لاستعلام مقترح تلقائيًا.
للعثور على عناوين شوارع متقاطعة، يجب عليك ترميز URI للتعامل مع الأحرف الخاصة في العنوان. ضع في اعتبارك مثال العنوان هذا: الشارع الأول وشارع الاتحاد، سياتل. هنا، قم بترميز حرف العطف (&) قبل إرسال الطلب.
نوصي بتشفير بيانات الأحرف في URI. في URI، تقوم بترميز جميع الأحرف باستخدام علامة النسبة المئوية (%) وقيمة سداسية عشرية مكونة من حرفين تتوافق مع رمز UTF-8 للأحرف.
في بحث POI، يمكنك طلب نتائج POI بالاسم. على سبيل المثال، يمكنك البحث عن شركة بالاسم.
نوصي بشدة باستخدام المعلمة countrySet لتحديد البلدان/المناطق التي يحتاج تطبيقك فيها إلى تغطية. السلوك الافتراضي هو البحث في العالم بأسره. قد يعرض هذا البحث الواسع نتائج غير ضرورية، وقد يستغرق البحث وقتًا طويلاً.
البحث عن العلامة التجارية
لتحسين ملاءمة النتائج والمعلومات الواردة في الاستجابة، تتضمن استجابة بحث POI معلومات العلامة التجارية. يمكنك استخدام هذه المعلومات لمزيد من تحليل الاستجابة.
في الطلب، يمكنك إرسال قائمة بأسماء العلامات التجارية مفصولة بفواصل. استخدم القائمة لقصر النتائج على علامات تجارية معينة من خلال تعيين المعلمة brandSet. في قائمتك، لا يهم ترتيب العناصر. عندما تقدم قوائم علامات تجارية متعددة، يجب أن تنتمي النتائج التي يتم إرجاعها إلى واحدة على الأقل من قوائمك.
لاستكشاف البحث عن العلامة التجارية، دعنا نطلب بحث فئة POI. في المثال التالي، نبحث عن محطات وقود بالقرب من حرم Microsoft في ريدموند، واشنطن. تعرض الاستجابة معلومات العلامة التجارية لكل نقطة مهمة تم إرجاعها.
باستخدام واجهة برمجة تطبيقات البحث POI، يمكنك البحث عن المطارات باستخدام رمزها الرسمي. على سبيل المثال، يمكنك استخدام SEA للعثور على مطار سياتل تاكوما الدولي:
لاسترداد نتائج POI حول موقع معين، يمكنك محاولة استخدام Search Nearby. تقوم نقطة النهاية بإرجاع نتائج POI فقط. لا يأخذ في معامل طلب البحث.
للحد من النتائج، نوصي بضبط نصف القطر.
فهم الردود
لنعثر على عنوان في سياتل عن طريق تقديم طلب بحث عن العناوين إلى خرائط Azure خدمة البحث. في عنوان URL للطلب التالي، قمنا بتعيين المعلمة countrySet على US للبحث عن العنوان في الولايات المتحدة.
عنوان النقطة: النقاط على الخريطة التي لها عنوان محدد مع اسم الشارع ورقمه. يوفر Point Address أعلى مستوى من الدقة للعناوين.
نطاق العنوان: نطاق نقاط العنوان التي تم إقحامها من بداية ونهاية الشارع.
الجغرافيا: المناطق على الخريطة التي تمثل التقسيمات الإدارية للأرض، على سبيل المثال، البلد/المنطقة أو الولاية أو المدينة.
نقطة مهمة: نقاط على الخريطة تستحق الاهتمام وقد تكون مثيرة للاهتمام.
الشارع: شوارع على الخريطة. يتم تحديد العناوين لإحداثيات خطوط الطول والعرض للشارع الذي يحتوي على العنوان. قد لا تتم معالجة رقم المنزل.
تقاطع الشارع: التقاطعات. تمثل الشوارع المتقاطعة التقاطعات حيث يتقاطع شارعان.
استجابة
لنلق نظرة على بنية الاستجابة. في الاستجابة التالية، تختلف أنواع الكائنات الناتجة. إذا نظرت بعناية، سترى ثلاثة أنواع من كائنات النتائج:
عنوان النقطة
الشارع
الشارع العرضي
لاحظ أن البحث عن العنوان لا يُرجع النقاط المهمة.
تشير المعلمة Score لكل كائن استجابة إلى كيفية ارتباط درجة المطابقة بنتائج الكائنات الأخرى في نفس الاستجابة. لمزيد من المعلومات حول معلمات كائن الاستجابة، راجع الحصول على عنوان البحث.
يمكن أن يشتمل نوع الاستجابة الهندسة على معرف الشكل الهندسي الذي يتم إرجاعه في الكائن dataSources ضمن geometry وid. على سبيل المثال، يمكنك استخدام خدمة مضلع البحث لطلب البيانات الهندسية بتنسيق GeoJSON. باستخدام هذا التنسيق، يمكنك الحصول على مخطط لمدينة أو مطار لمجموعة من الكيانات. يمكنك بعد ذلك استخدام بيانات الحدود هذه من أجل إعداد السياج الجغرافي أو البحث عن النقاط المهمة داخل الهندسة .
يمكن أن تتضمن الاستجابات ل "عنوان البحث" أو "البحث الغامض " المعرف الهندسي الذي يتم إرجاعه في dataSources الكائن ضمن geometry و id:
JSON
"dataSources": {
"geometry": {
"id": "00005557-4100-3c00-0000-000059690938" // The geometry ID is returned in the dataSources object under "geometry" and "id".
}
}
Use more advanced features of Azure AI Search to improve your existing search solutions. Learn how to change the ranking on documents, boost the most important terms to your organization, and allow searching in multiple languages.