استخدام مفاتيح واجهة برمجة التطبيقات لمصادقة البحث المعرفي في Azure
يستخدم البحث المعرفي المصادقة المستندة إلى المفتاح كمنهجية مصادقة أساسية. بالنسبة للطلبات الواردة إلى نقطة نهاية خدمة بحث، مثل الطلبات التي تنشئ فهرسا أو تستفسر عنه، فإن مفاتيح واجهة برمجة التطبيقات هي خيار المصادقة الوحيد المتاح بشكل عام لديك. يمكن لبعض سيناريوهات الطلبات الصادرة، وخاصة تلك التي تتضمن مفهرسات، استخدام هويات وأدوار Azure Active Directory.
ملاحظة
التخويل لعمليات مستوى البيانات باستخدام التحكم في الوصول المستند إلى دور Azure (RBAC) قيد المعاينة الآن. يمكنك استخدام إمكانية المعاينة هذه لتكملة مفاتيح واجهة برمجة التطبيقات أو استبدالها في طلبات فهرس البحث.
استخدام مفاتيح واجهة برمجة التطبيقات في البحث
يتم إنشاء مفاتيح واجهة برمجة التطبيقات عند إنشاء الخدمة. يعتبر تمرير مفتاح API صالح على الطلب دليلا على أن الطلب من عميل معتمد. هناك نوعان من المفاتيح. تنقل مفاتيح المسؤول أذونات الكتابة على الخدمة وتمنح أيضا حقوق الاستعلام عن معلومات النظام. تنقل مفاتيح الاستعلام أذونات القراءة ويمكن استخدامها بواسطة التطبيقات للاستعلام عن فهرس معين.
عند الاتصال بخدمة بحث، يجب أن تتضمن جميع الطلبات مفتاح واجهة برمجة تطبيقات تم إنشاؤه خصيصا لخدمتك.
في حلول REST، يتم تحديد مفتاح واجهة برمجة التطبيقات عادة في رأس الطلب
في حلول .NET ، غالبا ما يتم تحديد مفتاح كإعداد تكوين ثم يتم تمريره كبيانات اعتماد AzureKeyCredential
يمكنك عرض مفاتيح واجهة برمجة التطبيقات وإدارتها في مدخل Azure، أو من خلال PowerShell أو Azure CLI أو REST API.
ما هو مفتاح واجهة برمجة التطبيقات؟
مفتاح API عبارة عن سلسلة فريدة تتكون من أرقام وحروف يتم إنشاؤها عشوائيا يتم تمريرها في كل طلب إلى خدمة البحث. ستقبل الخدمة الطلب ، إذا كان كل من الطلب نفسه والمفتاح صالحين.
يتم استخدام نوعين من المفاتيح للوصول إلى خدمة البحث: المسؤول (للقراءة والكتابة) والاستعلام (للقراءة فقط).
| المفتاح | الوصف | الحدود |
|---|---|---|
| مسؤول | يمنح الحقوق الكاملة لجميع العمليات، بما في ذلك القدرة على إدارة الخدمة وإنشاء الفهارس والمفهرسات ومصادر البيانات وحذفها. يتم إنشاء مفتاحي مسؤول، يشار إليهما باسم المفاتيح الأساسيةوالثانوية في البوابة الإلكترونية، عند إنشاء الخدمة ويمكن إعادة إنشائهما بشكل فردي عند الطلب. يسمح لك وجود مفتاحين بتمرير مفتاح واحد أثناء استخدام المفتاح الثاني لاستمرار الوصول إلى الخدمة. يتم تحديد مفاتيح المسؤول فقط في رؤوس طلبات HTTP. لا يمكنك وضع مفتاح واجهة برمجة تطبيقات المشرف في عنوان URL. |
الحد الأقصى 2 لكل خدمة |
| الاستعلام | يمنح حق الوصول للقراءة فقط إلى الفهارس والمستندات، ويتم توزيعه عادة على تطبيقات العميل التي تصدر طلبات البحث. يتم إنشاء مفاتيح الاستعلام عند الطلب. يمكن تحديد مفاتيح الاستعلام في رأس طلب HTTP لعملية البحث أو الاقتراح أو البحث. بدلا من ذلك، يمكنك تمرير مفتاح طلب بحث كمعلمة على عنوان URL. استنادا إلى كيفية صياغة تطبيق العميل للطلب، قد يكون من الأسهل تمرير المفتاح كمعلمة استعلام: GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key] |
50 لكل خدمة |
بصريا، لا يوجد تمييز بين مفتاح المسؤول أو مفتاح الاستعلام. كلا المفتاحين عبارة عن سلاسل تتكون من 32 حرفا أبجديا رقميا تم إنشاؤه عشوائيا. إذا فقدت تعقب نوع المفتاح المحدد في التطبيق الخاص بك، يمكنك التحقق من قيم المفاتيح في البوابة الإلكترونية.
ملاحظة
يعتبر تمرير البيانات الحساسة مثل api-key عنوان URI للطلب ممارسة أمنية سيئة. لهذا السبب، يقبل Azure Cognitive Search فقط مفتاح استعلام كمفتاح api-key في سلسلة الاستعلام، ويجب تجنب القيام بذلك ما لم تكن محتويات الفهرس متاحة للجمهور. كقاعدة عامة، نوصي بتمرير عنوان الطلب الخاص بك api-key .
البحث عن المفاتيح الموجودة
يمكنك الحصول على مفاتيح الوصول في البوابة الإلكترونية أو من خلال PowerShell أو Azure CLI أو REST API.
تسجيل الدخول إلى مدخل Microsoft Azure.
أدرج خدمات البحث لاشتراكك.
حدد الخدمة وفي صفحة نظرة عامة، انقر فوق الإعدادات> مفاتيح لعرض مفاتيح المسؤول والاستعلام.
إنشاء مفاتيح استعلام
تستخدم مفاتيح الاستعلام للوصول للقراءة فقط إلى المستندات داخل فهرس للعمليات التي تستهدف مجموعة مستندات. استعلامات البحث والتصفية والاقتراحات هي جميع العمليات التي تأخذ مفتاح استعلام. تتطلب أي عملية للقراءة فقط ترجع بيانات النظام أو تعريفات الكائنات، مثل تعريف فهرس أو حالة مفهرس، مفتاح مسؤول.
يعد تقييد الوصول والعمليات في تطبيقات العميل أمرا ضروريا لحماية أصول البحث على خدمتك. استخدم دائما مفتاح استعلام بدلا من مفتاح مسؤول لأي استعلام ينشأ من تطبيق عميل.
تسجيل الدخول إلى مدخل Microsoft Azure.
أدرج خدمات البحث لاشتراكك.
حدد الخدمة وفي صفحة نظرة عامة، انقر فوق الإعدادات>مفاتيح.
انقر على إدارة مفاتيح الاستعلام.
استخدم مفتاح الاستعلام الذي تم إنشاؤه بالفعل لخدمتك، أو أنشئ ما يصل إلى 50 مفتاح استعلام جديدا. لم يتم تسمية مفتاح الاستعلام الافتراضي، ولكن يمكن تسمية مفاتيح استعلام إضافية لسهولة الإدارة.
ملاحظة
يمكن العثور على مثال التعليمات البرمجية الذي يعرض استخدام مفتاح الاستعلام في DotNetHowTo.
إعادة إنشاء مفاتيح المسؤول
يتم إنشاء مفتاحي مسؤول لكل خدمة بحيث يمكنك تدوير مفتاح أساسي، باستخدام المفتاح الثانوي لاستمرارية الأعمال.
- في صفحة الإعدادات>المفاتيح، انسخ المفتاح الثانوي.
- بالنسبة لجميع التطبيقات، قم بتحديث إعدادات مفتاح API لاستخدام المفتاح الثانوي.
- إعادة إنشاء المفتاح الأساسي.
- قم بتحديث كافة التطبيقات لاستخدام المفتاح الأساسي الجديد.
إذا قمت عن غير قصد بإعادة إنشاء كلا المفتاحين في نفس الوقت، فستفشل جميع طلبات العميل باستخدام هذين المفتاحين مع حظر HTTP 403. ومع ذلك ، لا يتم حذف المحتوى ولا يتم قفلك نهائيا.
لا يزال بإمكانك الوصول إلى الخدمة من خلال البوابة الإلكترونية أو برمجيا. تعمل وظائف الإدارة من خلال معرف اشتراك وليس مفتاح واجهة برمجة تطبيقات الخدمة ، وبالتالي تظل متاحة حتى إذا لم تكن مفاتيح واجهة برمجة التطبيقات الخاصة بك كذلك.
بعد إنشاء مفاتيح جديدة عبر البوابة الإلكترونية أو طبقة الإدارة، تتم استعادة الوصول إلى المحتوى الخاص بك (الفهارس والمفهرسات ومصادر البيانات وخرائط المرادفات) بمجرد حصولك على المفاتيح الجديدة وتوفير هذه المفاتيح عند الطلب.
مفاتيح واجهة برمجة التطبيقات الآمنة
تحدد تعيينات الأدوار من يمكنه قراءة المفاتيح وإدارتها. يمكن لأعضاء الأدوار التالية عرض المفاتيح وإعادة إنشائها: المالك والمساهم والمساهمون في خدمة البحث. لا يمكن لدور القارئ الوصول إلى مفاتيح واجهة برمجة التطبيقات.
يمكن لمسؤولي الاشتراك عرض جميع مفاتيح واجهة برمجة التطبيقات وإعادة إنشائها. كإجراء احترازي، راجع تعيينات الأدوار لفهم من لديه حق الوصول إلى مفاتيح المسؤول.
- انتقل إلى صفحة خدمة البحث في مدخل Azure.
- في جزء التنقل الأيمن، حدد التحكم في الوصول (IAM)، ثم حدد علامة التبويب تعيينات الأدوار .
- قم بتعيين النطاق إلى هذا المورد لعرض تعيينات الأدوار لخدمتك.