مكتبة عميل خرائط Azure Search ل JavaScript - الإصدار 1.0.0-beta.2

/TypeScript

خدمة Azure Maps Search عبارة عن مجموعة من RESTful APIs المصممة لمساعدة المطورين في البحث عن العناوين والأماكن وقوائم الأعمال حسب الاسم والفئة والمعلومات الجغرافية الأخرى. بالإضافة إلى دعم الترميز الجغرافي التقليدي، يمكن للخدمات أيضاً عكس عناوين الرمز الجغرافي وعبر الشوارع استناداً إلى خطوط العرض وخط الطول. يمكن استخدام قيم خط الطول والعرض التي يتم إرجاعها بواسطة البحث كمعلمات في خدمات Azure Maps الأخرى، مثل خدمات المسار والطقس.

تحتوي هذه الحزمة على SDK غير متحول (يعمل في كل من Node.js والمستعرضات) لعميل خرائط Azure Search.

التعليمات البرمجية | المصدر الحزمة (NPM) | عينات | معلومات المنتج

الشروع في العمل

البيئات المعتمدة حاليًا

• إصدارات "LTS" من "Node.js".
• أحدث إصدارات Safari وChrome وEdge وFirefox.

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

• اشتراك Azure.
• حساب خرائط Azure. يمكنك إنشاء المورد عبر مدخل Microsoft Azure أو Azure PowerShell أو Azure CLI.

إذا كنت تستخدم Azure CLI، فاستبدل <resource-group-name> و <map-account-name> من اختيارك، وحدد مستوى تسعير مناسبا بناء على احتياجاتك عبر المعلمة <sku-name> . يرجى الرجوع إلى هذه الصفحة لمزيد من التفاصيل.

az maps account create --resource-group <resource-group-name> --name <map-account-name> --sku <sku-name>

تثبيت @azure/maps-searchالحزمة

قم بتثبيت مكتبة عميل خرائط Azure Search باستخدام npm:

npm install @azure/maps-search

إنشاء ومصادقة MapsSearchClient

لإنشاء كائن عميل للوصول إلى واجهات برمجة تطبيقات البحث خرائط Azure، ستحتاج إلى كائنcredential. يمكن لعميل خرائط Azure Search استخدام بيانات اعتماد Azure Active Directory أو بيانات اعتماد Azure Key للمصادقة.

استخدام بيانات اعتماد Azure Active Directory

يمكنك المصادقة باستخدام Azure Active Directory باستخدام مكتبة Azure Identity. لاستخدام موفر DefaultAzureCredential الموضح أدناه، أو موفري بيانات الاعتماد الآخرين المقدمين مع Azure SDK، يرجى تثبيت الحزمة @azure/identity :

npm install @azure/identity

ستحتاج أيضا إلى تسجيل تطبيق AAD جديد ومنح حق الوصول إلى خرائط Azure عن طريق تعيين الدور المناسب لمدير الخدمة الخاص بك. يرجى الرجوع إلى صفحة إدارة المصادقة .

قم بتعيين قيم معرف العميل ومعرف المستأجر وسر العميل لتطبيق AAD كمتغيرات بيئة: AZURE_CLIENT_ID، ، AZURE_TENANT_ID. AZURE_CLIENT_SECRET

ستحتاج أيضا إلى تحديد مورد خرائط Azure الذي تنوي استخدامه عن طريق تحديد clientId في خيارات العميل. يمكن العثور على معرف عميل مورد خرائط Azure في أقسام المصادقة في مورد خرائط Azure. يرجى الرجوع إلى الوثائق حول كيفية العثور عليه.

const { MapsSearchClient } = require("@azure/maps-search");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const client = new MapsSearchClient(credential, "<maps-account-client-id>");

استخدام بيانات اعتماد مفتاح الاشتراك

يمكنك المصادقة باستخدام مفتاح اشتراك خرائط Azure.

const { MapsSearchClient, AzureKeyCredential } = require("@azure/maps-search");

const credential = new AzureKeyCredential("<subscription-key>");
const client = new MapsSearchClient(credential);

المفاهيم الرئيسية

MapsSearchClient

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

أمثلة

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

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

طلب إحداثيات خط الطول والعرض لعنوان

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

const searchResult = await client.searchAddress("400 Broad, Seattle");
for (const {
  position: { lat, lon },
} of searchResult.results) {
  console.log(`Latitude: ${lat}, Longitude: ${lon}`);
}

البحث عن عنوان أو نقطة اهتمام

يمكنك استخدام البحث الغامض للبحث في عنوان أو نقطة اهتمام (POI). يوضح المثال التالي كيفية البحث عن pizza عبر نطاق بلد معين (Franceفي هذا المثال).

const fuzzySearchResult = await client.fuzzySearch({ query: "pizza", countryCodeFilter: ["fr"] });
for (const result of fuzzySearchResult.results) {
  console.log(result);
}

إجراء بحث عكسي عن العنوان لترجمة موقع الإحداثيات إلى عنوان الشارع

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

const coordinates: LatLon = [47.59118, -122.3327]; // [latitude, longitude]

const { addresses } = await client.reverseSearchAddress(coordinates);
for (const { address } of addresses) {
  console.log(address);
}

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

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

const coordinates: LatLon = [47.59118, -122.3327];

const { addresses } = await client.reverseSearchCrossStreetAddress(coordinates);
for (const { address } of addresses) {
  console.log(address);
}

استكشاف الأخطاء وإصلاحها

تسجيل الدخول

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. للاطلاع على سجل لطلبات HTTP واستجاباته، قم بتعيين AZURE_LOG_LEVELمتغير البيئة إلى info. بدلًا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق الاتصال setLogLevelبـ @azure/logger:

const { setLogLevel } = require("@azure/logger");
setLogLevel("info");

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

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

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

المساهمة

إذا كنت ترغب في المساهمة في هذه المكتبة، يرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.

المشاريع ذات الصلة

• Microsoft Azure SDK ل JavaScript