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

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

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

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

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

يجب إكمال الخطوات التالية لكل من أحمال عمل التطوير والإنتاج المحلية:

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

إنشاء مورد الذكاء الاصطناعي Search

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

تثبيت مكتبة عميل Azure Identity

قبل العمل محليا بدون مفتاح، قم بتحديث التعليمات البرمجية الممكنة الذكاء الاصطناعي Search باستخدام مكتبة عميل Azure Identity.

NET.

تثبيت مكتبة عميل Azure Identity ل .NET:

dotnet add package Azure.Identity

Java

تثبيت مكتبة عميل Azure Identity ل Java مع ملف POM التالي:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.10.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

JavaScript

تثبيت مكتبة عميل Azure Identity ل JavaScript:

npm install --save @azure/identity

Python

تثبيت مكتبة عميل Azure Identity ل Python:

pip install azure-identity

تحديث التعليمات البرمجية المصدر لاستخدام DefaultAzureCredential

تتيح لك مكتبة DefaultAzureCredential Azure Identity تشغيل نفس التعليمات البرمجية في بيئة التطوير المحلية وفي سحابة Azure. إنشاء بيانات اعتماد واحدة وإعادة استخدام مثيل بيانات الاعتماد حسب الحاجة للاستفادة من التخزين المؤقت للرمز المميز.

NET.

لمزيد من المعلومات حول DefaultAzureCredential .NET، راجع مكتبة عميل Azure Identity ل .NET.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

Java

لمزيد من المعلومات حول DefaultAzureCredential Java، راجع مكتبة عميل Azure Identity ل Java.

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

JavaScript

لمزيد من المعلومات حول DefaultAzureCredential JavaScript، راجع مكتبة عميل Azure Identity ل JavaScript.

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

Python

لمزيد من المعلومات حول DefaultAzureCredential Python، راجع مكتبة عميل Azure Identity ل Python.

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.windows.net"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

التطوير المحلي

يتضمن التطوير المحلي بدون مفتاح الخطوات التالية:

• قم بتعيين هويتك الشخصية باستخدام أدوار RBAC على مورد معين.
• استخدم أداة للمصادقة مع Azure.
• إنشاء متغيرات البيئة للمورد الخاص بك.

أدوار التطوير المحلي

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

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

ابحث عن هويتك الشخصية باستخدام إحدى الأدوات التالية. استخدم هذه الهوية كقيمة <identity-id> .

Azure CLI

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

   az login
   

2. احصل على هويتك الشخصية.

   az ad signed-in-user show \
       --query id -o tsv
   

3. تعيين دور التحكم في الوصول المستند إلى الدور (RBAC) إلى هوية مجموعة الموارد.

   az role assignment create \
       --role "<role-name>" \
       --assignee "<identity-id>" \
       --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
   

Azure PowerShell

1. سجل الدخول باستخدام PowerShell.

   Connect-AzAccount
   

2. احصل على هويتك الشخصية.

   (Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
   

3. تعيين دور التحكم في الوصول المستند إلى الدور (RBAC) إلى هوية مجموعة الموارد.

   New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "<role-name>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
   

مدخل Microsoft Azure

1. استخدم الخطوات الموجودة هنا: ابحث عن معرف عنصر المستخدم في مدخل Microsoft Azure.

2. استخدم الخطوات الموجودة في فتح صفحة إضافة تعيين دور في مدخل Microsoft Azure.

عند الاقتضاء، استبدل <identity-id>و <subscription-id>و <resource-group-name> بقيمك الفعلية.

المصادقة للتطوير المحلي

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

NET.

حدد أداة للمصادقة أثناء التطوير المحلي.

Java

حدد أداة للمصادقة أثناء التطوير المحلي.

JavaScript

حدد أداة للمصادقة أثناء التطوير المحلي.

Python

حدد أداة للمصادقة أثناء التطوير المحلي.

تكوين متغيرات البيئة للتطوير المحلي

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

إنشاء متغير بيئة يسمى AZURE_SEARCH_ENDPOINT لنقطة نهاية Azure الذكاء الاصطناعي Search. يحتوي عنوان URL هذا بشكل عام على التنسيق https://<YOUR-RESOURCE-NAME>.search.windows.net/.

أحمال عمل المنتجات

يتضمن توزيع أحمال عمل الإنتاج الخطوات التالية:

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

أدوار أحمال عمل الإنتاج

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

يتم اقتراح الدور التالي لتطبيق إنتاج:

اسم الدور	المعرّف‬
قارئ بيانات فهرس البحث	1407120a-92aa-4202-b7e9-c0e197c71c8f

المصادقة لأحمال عمل الإنتاج

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

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

main.bicep يستدعي الملف التعليمات البرمجية العامة ل Bicep التالية لإنشاء أي دور. لديك خيار إنشاء أدوار RBAC متعددة، مثل واحد للمستخدم وآخر للإنتاج. يسمح لك هذا بتمكين كل من بيئات التطوير والإنتاج داخل نفس توزيع Bicep.

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

تكوين متغيرات البيئة لأحمال عمل الإنتاج

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

إنشاء متغيرات البيئة لمورد Azure الذكاء الاصطناعي Search المنشور وبدون مفتاح:

• AZURE_SEARCH_ENDPOINT: عنوان URL هذا هو نقطة الوصول لمورد Azure الذكاء الاصطناعي Search. يحتوي عنوان URL هذا بشكل عام على التنسيق https://<YOUR-RESOURCE-NAME>.search.windows.net/.
• AZURE_CLIENT_ID: هذه هي الهوية التي يجب المصادقة بها.

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

• دليل مطور الاتصالات بدون مفتاح
• أدوار Azure المضمنة
• تعيين متغيرات البيئة