التشغيل السريع: الاتصال بخدمة بحث

في هذا التشغيل السريع، يمكنك استخدام التحكم في الوصول المستند إلى الدور (RBAC) ومعرف Microsoft Entra لإنشاء اتصال بدون مفتاح بخدمة Azure الذكاء الاصطناعي Search. ثم يمكنك استخدام Python في تعليمة Visual Studio برمجية للتفاعل مع الخدمة الخاصة بك.

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

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.

• خدمة Azure الذكاء الاصطناعي Search في أي منطقة أو مستوى.

• Azure CLI للمصادقة بدون مفتاح مع معرف Microsoft Entra.

• تعليمة Visual Studio برمجية مع ملحق Pythonوحزمة Jupyter.

تكوين الوصول المستند إلى الدور

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

لتكوين الوصول:

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

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

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

   

4. من الجزء الأيمن، حدد Access control (IAM).

5. حدد إضافة>تعيين دور.

   

6. تعيين دور Search Service Contributor إلى حساب المستخدم أو الهوية المدارة.

7. كرر تعيين الدور ل Search Index Data Contributor.

الحصول على معلومات الخدمة

في هذا القسم، يمكنك استرداد معرف الاشتراك ونقطة النهاية لخدمة Azure الذكاء الاصطناعي Search. إذا كان لديك اشتراك واحد فقط، فتخط معرف الاشتراك واسترد نقطة النهاية فقط. يمكنك استخدام هذه القيم في المقاطع المتبقية من هذا التشغيل السريع.

للحصول على معلومات الخدمة الخاصة بك:

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

2. من الجزء الأيمن، حدد Overview.

3. دون معرف الاشتراك ونقطة النهاية.

   

تسجيل الدخول إلى Azure

قبل الاتصال بخدمة Azure الذكاء الاصطناعي Search، استخدم Azure CLI لتسجيل الدخول إلى الاشتراك الذي يحتوي على الخدمة. تؤسس هذه الخطوة هوية Microsoft Entra الخاصة بك، والتي DefaultAzureCredential تستخدم لمصادقة الطلبات في القسم التالي.

لتسجيل الدخول:

1. على النظام المحلي، افتح أداة سطر الأوامر.

2. تحقق من الاشتراك النشط والمستأجر في بيئتك المحلية.

   az account show
   

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

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

الاتصال ب Azure الذكاء الاصطناعي Search

ملاحظه

يوضح هذا القسم نمط Python الأساسي للاتصالات بدون مفتاح. للحصول على إرشادات شاملة، راجع بداية سريعة محددة أو درس تعليمي، مثل Quickstart: Agentic Retrival.

يمكنك استخدام دفاتر ملاحظات Python في تعليمة Visual Studio برمجية لإرسال الطلبات إلى خدمة Azure الذكاء الاصطناعي Search. لطلب المصادقة، استخدم DefaultAzureCredential الفئة من مكتبة Azure Identity.

للاتصال باستخدام Python:

1. على النظام المحلي، افتح تعليمة Visual Studio برمجية.

2. قم بإنشاء ملف .ipynb.

3. إنشاء خلية تعليمات برمجية azure-identity لتثبيت المكتبات و azure-search-documents .

   pip install azure-identity azure-search-documents
   

4. إنشاء خلية تعليمات برمجية أخرى للمصادقة والاتصال بخدمة البحث.

   import json
   from azure.identity import DefaultAzureCredential
   from azure.search.documents.indexes import SearchIndexClient
   
   service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
   credential = DefaultAzureCredential()
   client = SearchIndexClient(endpoint = service_endpoint, credential = credential)
   
   # List existing indexes
   indexes = client.list_indexes()
   
   for index in indexes:
      index_dict = index.as_dict()
      print(json.dumps(index_dict, indent = 2))
   

5. قم بتعيين service_endpoint إلى القيمة التي حصلت عليها في الحصول على معلومات الخدمة.

6. حدد Run All لتشغيل كل من خلايا التعليمات البرمجية.

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

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

إذا واجهت خطأ 401، فاتبع خطوات استكشاف الأخطاء وإصلاحها هذه:

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

• إعادة النظر في تسجيل الدخول إلى Azure. يجب تسجيل الدخول إلى الاشتراك الذي يحتوي على خدمة البحث.

• تأكد من أن متغير نقطة النهاية يحتوي على علامات اقتباس محيطة.

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

في هذا التشغيل السريع، يمكنك استخدام التحكم في الوصول المستند إلى الدور (RBAC) ومعرف Microsoft Entra لإنشاء اتصال بدون مفتاح بخدمة Azure الذكاء الاصطناعي Search. ثم يمكنك استخدام REST في تعليمة Visual Studio برمجية للتفاعل مع الخدمة الخاصة بك.

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

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.

• خدمة Azure الذكاء الاصطناعي Search في أي منطقة أو مستوى.

• Azure CLI للمصادقة بدون مفتاح مع معرف Microsoft Entra.

• تعليمة Visual Studio برمجية مع ملحق عميل REST.

تكوين الوصول المستند إلى الدور

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

لتكوين الوصول:

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

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

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

   

4. من الجزء الأيمن، حدد Access control (IAM).

5. حدد إضافة>تعيين دور.

   

6. تعيين دور Search Service Contributor إلى حساب المستخدم أو الهوية المدارة.

7. كرر تعيين الدور ل Search Index Data Contributor.

الحصول على معلومات الخدمة

في هذا القسم، يمكنك استرداد معرف الاشتراك ونقطة النهاية لخدمة Azure الذكاء الاصطناعي Search. إذا كان لديك اشتراك واحد فقط، فتخط معرف الاشتراك واسترد نقطة النهاية فقط. يمكنك استخدام هذه القيم في المقاطع المتبقية من هذا التشغيل السريع.

للحصول على معلومات الخدمة الخاصة بك:

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

2. من الجزء الأيمن، حدد Overview.

3. دون معرف الاشتراك ونقطة النهاية.

   

تسجيل الدخول إلى Azure

قبل الاتصال بخدمة Azure الذكاء الاصطناعي Search، استخدم Azure CLI لتسجيل الدخول إلى الاشتراك الذي يحتوي على الخدمة.

لتسجيل الدخول:

1. على النظام المحلي، افتح أداة سطر الأوامر.

2. تحقق من الاشتراك النشط والمستأجر في بيئتك المحلية.

   az account show
   

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

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

الحصول على رمز مميز

تتطلب استدعاءات واجهة برمجة تطبيقات REST تضمين رمز معرف Microsoft Entra. يمكنك استخدام هذا الرمز المميز لمصادقة الطلبات في القسم التالي.

للحصول على الرمز المميز الخاص بك:

1. باستخدام نفس أداة سطر الأوامر، تولد رمز وصول.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

2. دون ملاحظة عن إخراج الرمز المميز.

الاتصال ب Azure الذكاء الاصطناعي Search

ملاحظه

يوضح هذا القسم نمط REST الأساسي للاتصالات بدون مفتاح. للحصول على إرشادات شاملة، راجع بداية سريعة محددة أو درس تعليمي، مثل Quickstart: Agentic Retrival.

يمكنك استخدام ملحق عميل REST في تعليمة Visual Studio برمجية لإرسال الطلبات إلى خدمة Azure الذكاء الاصطناعي Search. للحصول على مصادقة الطلب، قم بتضمين Authorization عنوان مع الرمز المميز لمعرف Microsoft Entra الذي أنشأته مسبقا.

للاتصال باستخدام REST:

1. على النظام المحلي، افتح تعليمة Visual Studio برمجية.

2. إنشاء ملف .rest أو .http .

3. الصق المتغيرات التالية واطلب الطلب في الملف.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
   @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
   
   ### List existing indexes
   GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
      Content-Type: application/json
      Authorization: Bearer {{token}}
   

4. قم بتعيين @baseUrl إلى القيمة التي حصلت عليها في الحصول على معلومات الخدمة.

5. اضبط @token على القيمة التي حصلت عليها في رمز الحصول على الرمز.

6. ضمن ### List existing indexes، حدد إرسال طلب.

   يجب أن تتلقى استجابة HTTP/1.1 200 OK تشير إلى اتصال ناجح بخدمة البحث.

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

إذا واجهت خطأ 401، فاتبع خطوات استكشاف الأخطاء وإصلاحها هذه:

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

• إعادة النظر في تسجيل الدخول إلى Azure. يجب تسجيل الدخول إلى الاشتراك الذي يحتوي على خدمة البحث.

• تأكد من أن متغيرات نقطة النهاية والرمز المميز لا تحتوي على علامات اقتباس محيطة أو مسافات إضافية.

• تأكد من أن الرمز المميز الخاص بك لا يحتوي على @ الرمز في عنوان الطلب. على سبيل المثال، إذا كان المتغير هو @token، يجب أن يكون {{token}}المرجع في الطلب .

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

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

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