الاتصال ب البحث باستخدام الذكاء الاصطناعي في Azure باستخدام المفاتيح

يدعم البحث باستخدام الذكاء الاصطناعي في Azure كل من المصادقة القائمة على الهوية والمفتاحات (الافتراضية) للاتصالات بخدمة البحث الخاصة بك.

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

هام

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

المتطلبات

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

ممكّن بشكل افتراضي

في بوابة Azure، يتم تحديد المصادقة في صفحة Settings>Keys. الخيارات المعينة إما لمفاتيح API (افتراضية) أو كلاهما يسمح بمفاتيح API عند الطلب.

أنواع المفاتيح

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

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

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

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

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

بوابة

1. اذهب إلى خدمة البحث الخاصة بك في بوابة Azure.

2. من اللوحة اليسرى، اخترمفاتيح> لعرض مفاتيح الإدارة والاستعلام.

   

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

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

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

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

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

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

المرجع:مفاتيح المسؤول - الحصول على المفاتيح الاستعلامية - القائمة حسب خدمة البحث

Python

استخدم Azure SDK ل Python لاسترجاع مفاتيح API بشكل برمجي. تثبيت حزمة تطوير البرمجيات للإدارة:

pip install azure-mgmt-search azure-identity

شغل الكود التالي لإرجاع مفاتيح API للمسؤول والاستعلام:

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.search import SearchManagementClient

# Set up variables
subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"]
resource_group = "your-resource-group"
search_service_name = "your-search-service"

# Create the management client
credential = DefaultAzureCredential()
client = SearchManagementClient(credential, subscription_id)

# Get admin keys
admin_keys = client.admin_keys.get(resource_group, search_service_name)
print(f"Primary admin key: {admin_keys.primary_key}")
print(f"Secondary admin key: {admin_keys.secondary_key}")

# Get query keys
query_keys = client.query_keys.list_by_search_service(resource_group, search_service_name)
for key in query_keys:
    print(f"Query key '{key.name}': {key.key}")

المرجع:SearchManagementClient | AdminKeys | QueryKeys

بوويرشيل

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

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

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

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

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

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

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

استخدم المفاتيح على الاتصالات

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

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

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

بوابة

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

ومع ذلك، إذا قمت بتعطيل مفاتيح API >< وقمت بإعداد تعيين الأدوار، فإن بوابة Azure تستخدم تعيين الأدوار بدلا من ذلك.

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

تعيين مفتاح مسؤول في عنوان الطلب. لا يمكنك تمرير مفاتيح المسؤول على URI أو في نص الطلب.

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

@baseUrl=https://my-demo-search-service.search.windows.net
@adminApiKey=aaaabbbb-0000-cccc-1111-dddd2222eeee

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-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=2025-09-01&api-key={{queryApiKey}}

إشعار

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

Python

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

# Import libraries
from azure.search.documents import SearchClient
from azure.core.credentials import AzureKeyCredential
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Variables for endpoint, keys, index
search_endpoint: str = "https://<Put your search service NAME here>.search.windows.net/"
credential = AzureKeyCredential("Your search service query key")
index_name: str = "hotels-quickstart-python"

# Set up the client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Run the query
results =  search_client.search(query_type='simple',
    search_text="*" ,
    select='HotelName,Description,Tags',
    include_total_count=True)

print ('Total Documents Matching Query:', results.get_count())
for result in results:
    print(result["@search.score"])
    print(result["HotelName"])
    print(result["Tags"])
    print(f"Description: {result['Description']}")

بوويرشيل

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

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

استخدم متغيرا لاحتواء الاستعلام المؤهل بالكامل:

$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2025-09-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'

أرسل الطلب إلى خدمة البحث:

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

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

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

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

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

بوابة

1. اذهب إلى خدمة البحث الخاصة بك في بوابة Azure.

2. من اللوحة اليسرى، اخترمفاتيح> لعرض مفاتيح API.

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

   

واجهة برمجة التطبيقات 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=2025-05-01

بوويرشيل

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

Azure CLI

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

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

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

1. اذهب إلى خدمة البحث الخاصة بك في بوابة Azure.

2. من الجزء الأيمن، حدد Settings>Keys.

3. انسخ المفتاح الثانوي.

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

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

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

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

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

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

الانتقال من المفاتيح إلى الأدوار

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

• مفتاح المسؤول يتوافق مع أدوار مساهم خدمة البحثومساهم بيانات فهرس البحث .
• يتوافق مفتاح الاستعلام مع دور قارئ بيانات فهرس البحث .

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

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

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

1. اذهب إلى خدمة البحث الخاصة بك في بوابة Azure.

2. من اللوحة اليسرى، اختر التحكم في الوصول (IAM)، ثم اختر تبويب تعيين الأدوار .

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

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

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

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

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

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

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

المحتوى ذو الصلة

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