الاتصال إلى Azure الذكاء الاصطناعي Search باستخدام مصادقة المفتاح

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

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

إشعار

ملاحظة سريعة حول المصطلحات الرئيسية . مفتاح API هو GUID يستخدم للمصادقة. مصطلح منفصل، مفتاح المستند هو سلسلة فريدة في المحتوى المفهرس الذي يعرف المستندات بشكل فريد في فهرس البحث.

أنواع مفاتيح واجهة برمجة التطبيقات

هناك نوعان من المفاتيح المستخدمة لمصادقة طلب:

نوع	مستوى الأذونات	الحد الأقصى	كيفية الإنشاء
مسؤول	الوصول الكامل (القراءة والكتابة) لجميع عمليات المحتوى	2 1	يتم إنشاء مفتاحي مسؤول، يشار إليهما باسم المفاتيح الأساسيةوالثانوية في المدخل، عند إنشاء الخدمة ويمكن إعادة إنشائها بشكل فردي عند الطلب.
الاستعلام	الوصول للقراءة فقط، تم تحديد نطاقه لمجموعة المستندات الخاصة بفهرس البحث	50	يتم إنشاء مفتاح استعلام واحد مع الخدمة. يمكن إنشاء المزيد عند الطلب من قبل مسؤول خدمة البحث.

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

بصريا، لا يوجد تمييز بين مفتاح المسؤول أو مفتاح الاستعلام. كلا المفتاحين عبارة عن سلاسل تتكون من 52 حرفا أبجديا رقميا تم إنشاؤه عشوائيا. إذا فقدت تعقب نوع المفتاح المحدد في التطبيق الخاص بك، يمكنك التحقق من قيم المفتاح في المدخل.

استخدام مفاتيح واجهة برمجة التطبيقات على الاتصالات

يتم استخدام مفاتيح واجهة برمجة التطبيقات لطلبات مستوى البيانات (المحتوى)، مثل إنشاء فهرس أو الوصول إليه أو أي طلب آخر يتم تمثيله في واجهات برمجة تطبيقات REST للبحث. عند إنشاء الخدمة، يكون مفتاح API هو آلية المصادقة الوحيدة لعمليات مستوى البيانات، ولكن يمكنك استبدال أو تكملة مصادقة المفتاح بأدوار Azure إذا لم تتمكن من استخدام المفاتيح ذات التعليمات البرمجية المضمنة في التعليمات البرمجية الخاصة بك.

يتم استخدام مفاتيح مسؤول لإنشاء الكائنات أو تعديلها أو حذفها. يتم أيضا استخدام مفاتيح مسؤول لتعريفات عناصر GET ومعلومات النظام.

عادة ما يتم توزيع مفاتيح الاستعلام على تطبيقات العميل التي تصدر الاستعلامات.

واجهة برمجة التطبيقات REST

كيفية استخدام مفاتيح API في استدعاءات REST:

تعيين مفتاح مسؤول في عنوان الطلب. لا يمكنك تمرير مفاتيح المسؤول على URI أو في نص الطلب. يتم استخدام مفاتيح مسؤول لعملية create-read-update-delete وعلى الطلبات الصادرة إلى خدمة البحث نفسها، مثل LIST Indexes أو GET Service Statistics.

فيما يلي مثال على استخدام مفتاح API المسؤول على طلب إنشاء فهرس:

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

قم بتعيين مفتاح استعلام في عنوان طلب ل POST، أو على URI ل GET. يتم استخدام مفاتيح الاستعلام للعمليات التي تستهدف index/docs المجموعة: البحث في المستندات أو الإكمال التلقائي أو الاقتراح أو مستند GET.

فيما يلي مثال على استخدام مفتاح API للاستعلام على طلب البحث في المستندات (GET):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2023-11-01&api-key={{queryApiKey}}

إشعار

يعتبر تمرير البيانات الحساسة api-key مثل في طلب URI ممارسة أمنية سيئة. لهذا السبب، يقبل Azure الذكاء الاصطناعي Search مفتاح استعلام فقط ك api-key في سلسلة الاستعلام. كقاعدة عامة، نوصي بتمرير كعنوان api-key طلب.

بوويرشيل

كيفية استخدام مفاتيح واجهة برمجة التطبيقات في PowerShell:

تعيين مفاتيح واجهة برمجة التطبيقات في عنوان الطلب باستخدام بناء الجملة التالي:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

يمكن العثور على مثال برنامج نصي يوضح استخدام مفتاح API لعمليات مختلفة في التشغيل السريع: إنشاء فهرس Azure الذكاء الاصطناعي Search في PowerShell باستخدام واجهات برمجة تطبيقات REST.

المدخل

كيفية استخدام مفاتيح واجهة برمجة التطبيقات في مدخل Microsoft Azure:

• مصادقة المفتاح مضمنة. بشكل افتراضي، يحاول المدخل مفاتيح API أولا. ومع ذلك، إذا قمت بتعطيل مفاتيح واجهة برمجة التطبيقات وإعداد تعيينات الأدوار، فإن المدخل يستخدم تعيينات الأدوار بدلا من ذلك.

أذونات لعرض مفاتيح واجهة برمجة التطبيقات أو إدارتها

يتم نقل أذونات عرض مفاتيح واجهة برمجة التطبيقات وإدارتها من خلال تعيينات الأدوار. يمكن لأعضاء الأدوار التالية عرض المفاتيح وإعادة إنشائها:

• مالك
• مساهم
• مساهم خدمة البحث
• مسؤول istrator ومسؤول مشارك (كلاسيكي)

لا تتمتع الأدوار التالية بالوصول إلى مفاتيح واجهة برمجة التطبيقات:

• القارئ
• مساهم بيانات فهرس البحث
• قارئ بيانات فهرس البحث

البحث عن المفاتيح الموجودة

يمكنك عرض مفاتيح واجهة برمجة التطبيقات وإدارتها في مدخل Microsoft Azure، أو من خلال PowerShell أو Azure CLI أو REST API.

المدخل

1. سجل الدخول إلى مدخل Microsoft Azure وابحث عن خدمة البحث.

2. ضمن الإعدادات، حدد مفاتيح لعرض مفاتيح المسؤول والاستعلام.

بوويرشيل

1. تثبيت الوحدة النمطية Az.Search :

   Install-Module Az.Search
   

2. إرجاع مفاتيح المسؤول:

   Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>
   

3. إرجاع مفاتيح الاستعلام:

   Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>
   

Azure CLI

استخدم الأوامر التالية لإرجاع مفاتيح واجهة برمجة التطبيقات الخاصة بالمسؤول والاستعلام، على التوالي:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

واجهة برمجة التطبيقات REST

استخدم مفاتيح مسؤول القائمة أو مفاتيح استعلام القائمة في Management REST API لإرجاع مفاتيح واجهة برمجة التطبيقات.

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

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

إنشاء مفاتيح الاستعلام

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

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

المدخل

1. سجل الدخول إلى مدخل Microsoft Azure وابحث عن خدمة البحث.

2. ضمن الإعدادات، حدد مفاتيح لعرض مفاتيح واجهة برمجة التطبيقات.

3. ضمن إدارة مفاتيح الاستعلام، استخدم مفتاح الاستعلام الذي تم إنشاؤه بالفعل للخدمة، أو أنشئ مفاتيح استعلام جديدة. لم تتم تسمية مفتاح الاستعلام الافتراضي، ولكن يمكن تسمية مفاتيح الاستعلام الأخرى التي تم إنشاؤها لسهولة الإدارة.

   

بوويرشيل

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

Azure CLI

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

واجهة برمجة التطبيقات REST

استخدم Create Query Keys في Management REST API.

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

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

إعادة إنشاء مفاتيح المسؤول

يتم إنشاء مفتاحي إدارة لكل خدمة بحيث يمكنك تدوير مفتاح أساسي أثناء استخدام المفتاح الثانوي لاستمرارية الأعمال.

1. ضمن الإعدادات، حدد مفاتيح، ثم انسخ المفتاح الثانوي.

2. بالنسبة لجميع التطبيقات، قم بتحديث إعدادات مفتاح API لاستخدام المفتاح الثانوي.

3. إعادة إنشاء المفتاح الأساسي.

4. تحديث جميع التطبيقات لاستخدام المفتاح الأساسي الجديد.

إذا قمت بإعادة إنشاء كلا المفتاحين عن غير قصد في نفس الوقت، فستفشل جميع طلبات العميل التي تستخدم هذه المفاتيح مع HTTP 403 Forbidden. ومع ذلك، لا يتم حذف المحتوى ولا يتم تأمينك بشكل دائم.

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

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

مفاتيح API الآمنة

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

لا يمكن استخدام تشفير المفتاح المدار من قبل العميل لتشفير مفاتيح واجهة برمجة التطبيقات. يمكن تشفير CMK فقط للبيانات الحساسة داخل خدمة البحث نفسها (على سبيل المثال، محتوى الفهرس أو سلسلة الاتصال في تعريفات عناصر مصدر البيانات).

1. انتقل إلى صفحة خدمة البحث في مدخل Microsoft Azure.

2. في جزء التنقل الأيمن، حدد Access control (IAM)، ثم حدد علامة التبويب Role assignments .

3. في عامل تصفية الدور ، حدد الأدوار التي لديها إذن لعرض المفاتيح أو إدارتها (المالك والمساهم والمساهم في خدمة البحث). كيانات الأمان الناتجة المعينة لهذه الأدوار لها أذونات رئيسية في خدمة البحث.

4. كإجراء وقائي، تحقق أيضا من علامة التبويب Classic administrators لتحديد ما إذا كان لدى المسؤولين والمسؤولين المشاركين حق الوصول.

أفضل الممارسات

• استخدم مفاتيح واجهة برمجة التطبيقات فقط إذا لم يكن الكشف عن البيانات خطرا (على سبيل المثال، عند استخدام نموذج البيانات) وإذا كنت تعمل خلف جدار حماية. يعد التعرض لمفاتيح واجهة برمجة التطبيقات خطرا على كل من البيانات والاستخدام غير المصرح به لخدمة البحث الخاصة بك.

• تحقق دائما من التعليمات البرمجية والعينات ومواد التدريب قبل النشر للتأكد من أنك لم تترك مفاتيح API صالحة خلفك.

• بالنسبة لأحمال عمل الإنتاج، قم بالتبديل إلى معرف Microsoft Entra والوصول المستند إلى الدور. أو، إذا كنت ترغب في الاستمرار في استخدام مفاتيح واجهة برمجة التطبيقات، فتأكد دائما من مراقبة من لديه حق الوصول إلى مفاتيحواجهة برمجة التطبيقات وإعادة إنشاء مفاتيح واجهة برمجة التطبيقات على إيقاع منتظم.

(راجع أيضًا )

• الأمان في Azure الذكاء الاصطناعي Search
• التحكم في الوصول المستند إلى دور Azure في Azure الذكاء الاصطناعي Search
• إدارة باستخدام PowerShell