البرنامج التعليمي: البحث عن نقاط الاهتمام القريبة باستخدام خرائط Azure

مقالة
09/03/2024

يوضح هذا البرنامج التعليمي طريقة إعداد حساب باستخدام خرائط Microsoft Azure، ثم استخدام واجهات برمجة التطبيقات للخرائط للبحث عن نقطة اهتمام. في هذا البرنامج التعليمي، تتعلم كيفية:

أنشئ حساب خرائط Azure
استرداد مفتاح الاشتراك لحساب الخرائط
إنشاء صفحة ويب جديدة باستخدام واجهة برمجة تطبيقات التحكم في الخريطة
استخدام خدمة البحث في خرائط للعثور على نقطة اهتمام قريبة

المتطلبات الأساسية

في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

إشعار

ولمزيد من المعلومات حول مصادقة Azure Maps، راجع إدارة المصادقة في Azure Maps.

إنشاء خريطة جديدة

تعد Map Control API مكتبة عملاء ملائمة. تتيح لك واجهة برمجة التطبيقات (API) دمج الخرائط بسهولة في تطبيق الويب الخاص بك. إنه يخفي تعقيد مكالمات خدمة REST المجردة، ويعزز إنتاجيتك بمكونات قابلة للتخصيص. توضح لك الخطوات التالية طريقة إنشاء صفحة HTML ثابتة مضمنة في Map Control API.

على جهازك المحلي، أنشئ ملفا جديدا وقم بتسمياته MapSearch.html.

أضف مكونات HTML التالية إلى الملف:

 <!DOCTYPE html>
 <html>
 <head>
     <title>Map Search</title>
     <meta charset="utf-8" />

     <!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
     <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />
     <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

     <script>
     function GetMap(){
         //Add Map Control JavaScript code here.
     }
     </script>

     <style>
         html,
         body {
             width: 100%;
             height: 100%;
             padding: 0;
             margin: 0;
         }

         #myMap {
             width: 100%;
             height: 100%;
         }
     </style>
 </head>
 <body onload="GetMap()">
     <div id="myMap"></div>
 </body>
 </html>

بعض الأشياء التي يجب معرفتها فيما يتعلق بـ HTML أعلاه:

يتضمن رأس HTML ملفات موارد CSS وJavaScript التي تستضيفها مكتبة Azure Map Control.
يستدعي الحدث onload الموجود في نص الصفحة الوظيفة GetMap عند تحميل نص الصفحة.
GetMap تحتوي الدالة على تعليمة JavaScript البرمجية المضمنة المستخدمة للوصول إلى واجهات برمجة التطبيقات خرائط Azure. يتم إضافته في الخطوة التالية.

أضف التعليمات البرمجية GetMap JavaScript التالية إلى وظيفة ملف HTML. استبدل السلسلة <Your Azure Maps Subscription Key> بمفتاح الاشتراك الذي نسخته من حساب خرائط Azure.
```
//Instantiate a map object
var map = new atlas.Map("myMap", {
    view: 'Auto',

    // Add your Azure Maps subscription key. https://aka.ms/am-primaryKey
    authOptions: {
        authType: 'subscriptionKey',
        subscriptionKey: '<Your Azure Maps Subscription Key>'
    }
});
```
بعض الأشياء التي يجب معرفتها فيما يتعلق ب JavaScript هذا:
- جوهر الدالةGetMap، التي تهيئ واجهة برمجة تطبيقات التحكم في الخريطة لمفتاح حساب خرائط Azure الخاص بك.
- atlas هي مساحة الاسم التي تحتوي على واجهة برمجة التطبيقات والمكونات المرئية ذات الصلة.
- atlas.Map يوفر عنصر التحكم لخريطة ويب مرئية وتفاعلية.
احفظ التغييرات التي أجريتها على الملف وافتح صفحة HTML في المستعرض. الخريطة المعروضة هي الخريطة الأساسية التي يمكنك إجراؤها عن طريق الاتصال atlas.Map باستخدام مفتاح حسابك.
في الدالة GetMap ، بعد تهيئة الخريطة، أضف التعليمات البرمجية JavaScript التالية.
```
//Wait until the map resources are ready.
map.events.add('ready', function() {

    //Create a data source and add it to the map.
    datasource = new atlas.source.DataSource();
    map.sources.add(datasource);

    //Add a layer for rendering point data.
    var resultLayer = new atlas.layer.SymbolLayer(datasource, null, {
        iconOptions: {
            image: 'pin-round-darkblue',
            anchor: 'center',
            allowOverlap: true
        },
        textOptions: {
            anchor: "top"
        }
    });

    map.layers.add(resultLayer);
});
```
نبذة حول هذه التعليمات البرمجية:
- تتم إضافة حدث ready إلى الخريطة، والذي يتم تنشيطه عند تحميل موارد الخريطة بشكل نهائي وتكون الخريطة جاهزة للوصول إليها.
- في معالج أحداث الخريطة ready ، يتم إنشاء مصدر بيانات لتخزين بيانات النتائج.
- يتم إنشاء طبقة رمز وإرفاقها بمصدر البيانات. تحدد هذه الطبقة طريقة عرض البيانات الناتجة في مصدر البيانات. في هذه الحالة، يتم عرض النتيجة مع أيقونة دبوس دائري أزرق داكن، يتم توسيطها فوق إحداثيات النتائج التي تسمح بتداخل الأيقونات الأخرى.
- تتم إضافة الطبقة الناتجة إلى طبقات الخريطة.

إضافة قدرات البحث

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

تلميح

يقدم خرائط Azure مجموعة من وحدات npm النمطية خرائط Azure JavaScript REST SDK. تتضمن هذه الوحدات مكتبات العميل التي تبسط استخدام خدمات REST خرائط Azure في تطبيقات Node.js. للحصول على قائمة كاملة بالوحدات النمطية المتوفرة، راجع دليل مطوري JavaScript/TypeScript REST SDK (معاينة).

خدمة البحث

أضف كتلة البرنامج النصي التالية في معالج أحداث الخريطة ready . هذه هي التعليمات البرمجية لإنشاء استعلام البحث. يستخدم خدمة البحث غامض، واجهة برمجة تطبيقات بحث أساسية لخدمة البحث. يعالج خدمة البحث الغامض معظم المدخلات الغامضة مثل العناوين والأماكن ونقاط الاهتمام (POI). تبحث هذه التعليمة البرمجية عن محطات بنزين قريبة ضمن نصف القطر المحدد لخط الطول والعرض المقدمَين. ثم يتم استخراج مجموعة ميزات GeoJSON وإضافتها إلى مصدر البيانات، ما يؤدي تلقائيا إلى عرض البيانات على طبقة رمز الخرائط. يضبط الجزء الأخير من كتلة البرنامج النصي عرض الخرائط بالكاميرا باستخدام المربع المحيط للنتائج باستخدام خاصية setCamera الخاصة بالخريطة.
```
var query = 'gasoline-station';
var radius = 9000;
var lat = 47.64452336193245;
var lon = -122.13687658309935;
var url = `https://atlas.microsoft.com/search/poi/json?api-version=1.0&query=${query}&lat=${lat}&lon=${lon}&radius=${radius}`;

fetch(url, {
    headers: {
        "Subscription-Key": map.authentication.getToken()
    }
})
.then((response) => response.json())
.then((response) => {
    var bounds = [];

    //Extract GeoJSON feature collection from the response and add it to the datasource
    var data = response.results.map((result) => {
        var position = [result.position.lon, result.position.lat];
        bounds.push(position);
        return new atlas.data.Feature(new atlas.data.Point(position), { ...result });
    });
    datasource.add(data);

    //Set camera to bounds to show the results
    map.setCamera({
        bounds: new atlas.data.BoundingBox.fromLatLngs(bounds),
        zoom: 10,
        padding: 15
    });
});
```
احفظ ملف MapSearch.html وقم بتحديث المستعرض. يجب أن تشاهد الخريطة متمركزة في سياتل (Seattle) مزودة بإشارات دائرية زرقاء لمواقع محطات البنزين في المنطقة.
يمكنك رؤية البيانات الأولية التي تعرضها الخريطة عن طريق إدخال طلب HTTPRequest التالي في متصفحك. استبدال <Your Azure Maps Subscription Key> بمفتاح اشتراكك.
```
https://atlas.microsoft.com/search/poi/json?api-version=1.0&query=gasoline%20station&subscription-key={Your-Azure-Maps-Subscription-key}&lat=47.6292&lon=-122.2337&radius=100000
```

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

إضافة بيانات تفاعلية

لا تنظر الخريطة حتى الآن إلا إلى بيانات خط الطول/خط العرض لنتائج البحث. ومع ذلك، فإن JSON الخام الذي تعرضه خدمة Maps Search يحتوي على معلومات إضافية حول كل محطة وقود.ات إضافية حول كل محطة وقود. إدراج الاسم وعنوان الشارع. يمكنك دمج هذه البيانات في الخريطة باستخدام المربعات المنبثقة التفاعلية.

أضف الأسطر التالية من التعليمات البرمجية في معالج أحداث الخريطة ready بعد التعليمات البرمجية للاستعلام عن خدمة البحث الغامضة. تنشئ هذه التعليمة البرمجية مثيلا لنافذة منبثقة وتضيف حدث تمرير الماوس إلى طبقة الرمز.
```
// Create a popup but leave it closed so we can update it and display it later.
popup = new atlas.Popup();

//Add a mouse over event to the result layer and display a popup when this event fires.
map.events.add('mouseover', resultLayer, showPopup);
```
توفر واجهة برمجة التطبيقات atlas.Popup نافذة معلومات مثبتة في الموضع المطلوب على الخريطة.

أضف الأسطر التالية من التعليمات البرمجية في معالج أحداث الخريطة ready بعد التعليمات البرمجية لإنشاء مثيل منبثقة وإضافة حدث تمرير الماوس إلى طبقة الرمز. تعرض هذه التعليمة البرمجية نافذة منبثقة مع النتائج عند الماوس فوق نقطة اهتمام.

function showPopup(e) {
    //Get the properties and coordinates of the first shape that the event occurred on.

    var p = e.shapes[0].getProperties();
    var position = e.shapes[0].getCoordinates();

    //Create HTML from properties of the selected result.
    var html = `
      <div style="padding:5px">
        <div><b>${p.poi.name}</b></div>
        <div>${p.address.freeformAddress}</div>
        <div>${position[1]}, ${position[0]}</div>
      </div>`;

    //Update the content and position of the popup.
    popup.setPopupOptions({
        content: html,
        position: position
    });

    //Open the popup.
    popup.open(map);
}

احفظ الملف وقم بتحديث متصفحك. الآن الخريطة في المتصفح توضح المعلومات المنبثقة عند التمرير فوق أي من دبابيس البحث.

للحصول على التعليمات البرمجية المكتملة المستخدمة في هذا البرنامج التعليمي، راجع البرنامج التعليمي search على GitHub.
لعرض هذا النموذج المباشر، راجع Search for points of interest على موقع Azure Maps Code Samples.

الخطوات التالية

يوضح البرنامج التعليمي التالي طريقة عرض طريق بين موقعَين.

التوجيه إلى وجهة

مشاركة عبر