Az alkalmazást csatlakoztassa az Azure AI Kereséshez identitások használatával

Note

Azure AI Keresés a Azure portálon, REST API-kon és Azure SDK-k keresztül érhető el. Emellett a Foundry IQ-t is támogatja, amely a vállalati tartalmakat újrafelhasználható, engedélytudatos tudásbázisokká alakítja át az Microsoft Foundry portálon található ügynökök számára.

Az alkalmazáskódban beállíthat egy kulcs nélküli kapcsolatot Azure AI Keresés, amely Microsoft Entra ID és szerepköröket használ hitelesítéshez és engedélyezéshez. A legtöbb Azure szolgáltatáshoz irányuló alkalmazáskéréseket kulcsokkal vagy kulcs nélküli kapcsolatokkal kell hitelesíteni. A fejlesztőknek szorgalmasnak kell lenniük ahhoz, hogy a kulcsok ne legyenek biztonságos helyen elérhetővé. Bárki, aki hozzáfér a kulcshoz, hitelesítheti magát a szolgáltatásban. A kulcs nélküli hitelesítés jobb felügyeleti és biztonsági előnyöket biztosít a fiókkulcson keresztül, mivel nincs tárolandó kulcs (vagy kapcsolati karakterlánc).

Ez a cikk bemutatja, hogyan használható DefaultAzureCredential az alkalmazáskódban.

A kulcs nélküli kapcsolatok kódban való implementálásához kövesse az alábbi lépéseket:

• Szerepköralapú hozzáférés engedélyezése a keresési szolgáltatásban
• Szükség szerint állítsa be a környezeti változókat.
• Azure Identitástár hitelesítő adattípusának használatával hozzon létre egy Azure AI Keresés ügyfélobjektumot.

Előfeltételek

• Azure AI Keresés, bármely régió, de számlázható szintnek kell lennie (alapszintű vagy magasabb).

• A szerepköralapú hozzáférés engedélyezve van a keresési szolgáltatásban.

• Szerepkör-hozzárendelések Azure AI Keresés. Rendelje hozzá ezeket a szerepköröket az identitásához:

  • Keresési szolgáltatás közreműködője és keresési index adatszolgáltatója helyi fejlesztéshez (teljes hozzáférés)
  • Keresési index adatolvasó éles, csak olvasható lekérdezésekhez

  Részletes útmutatásért lásd: Szerepkörök hozzárendelése a fejlesztéshez.

Azure Identity-ügyfélkódtár telepítése

Kulcs nélküli megközelítés használatához frissítse az AI Search-kompatibilis kódot az Azure Identity ügyfélkódtárával.

.NET

Telepítse a .NET Azure Identity klienskönyvtárat és az Azure Search Documents klienskönyvtárat:

dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents

Java

Telepítse a Azure Identity klienstárat Java és a Azure Search Documents klienstárat a következő POM fájl segítségével:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.15.1</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

JavaScript

Telepítse a JavaScripthez készült Azure Identity ügyfélkódtárat és a Azure Keresési dokumentumok ügyfélkódtárat:

npm install --save @azure/identity @azure/search-documents

Python

Telepítse az Azure Identity ügyfélkönyvtárat Pythonhoz és az Azure Keresési dokumentumok ügyfélkönyvtárat:

pip install azure-identity azure-search-documents

Forráskód frissítése a DefaultAzureCredential használatára

Az Azure Identitástár DefaultAzureCredential lehetővé teszi ugyanazt a kódot a helyi fejlesztési környezetben és a Azure felhőben. Hozzon létre egyetlen hitelesítő adatot, és szükség szerint használja újra a hitelesítő adat példányát a token-gyorsítótárazás előnyeinek kihasználásához.

.NET

További információért a használatáról .NET-ben, tekintse meg az Azure Identity ügyfélkönyvtárát .NET-hez.

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);

Referencia:SearchClient, SearchIndexClient, DefaultAzureCredential

Java

További információért a Java DefaultAzureCredential-ról, lásd az Azure Identity klienskönyvtárat Java-hoz.

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();

Referencia:SearchClient, SearchIndexClient, DefaultAzureCredential

JavaScript

JavaScripttel kapcsolatban további információt az DefaultAzureCredential.

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
);

Referencia:SearchClient, SearchIndexClient, DefaultAzureCredential

Python

Az DefaultAzureCredential Pythonhoz kapcsolódó részleteket az Azure Identity ügyfélkönyvtára Pythonhoz című dokumentumban találja.

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

# Azure Public Cloud
audience = "https://search.azure.com"
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_name=index_name, 
    credential=credential, 
    audience=audience)

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

Referencia:SearchClient, SearchIndexClient, DefaultAzureCredential

A kapcsolat ellenőrzése

Az ügyfél beállítása után egy egyszerű művelet futtatásával ellenőrizze a kapcsolatot. Az alábbi példa a keresési szolgáltatás indexeit sorolja fel:

.NET

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

Java

// List indexes to verify connection
searchIndexClient.listIndexNames().forEach(System.out::println);

JavaScript

// List indexes to verify connection
for await (const name of indexClient.listIndexesNames()) {
  console.log(name);
}

Python

# List indexes to verify connection
for index in search_index_client.list_index_names():
    print(index)

A sikeres kapcsolat kinyomtatja az indexek nevét (vagy üres listát, ha nincsenek indexek). Ha hitelesítési hibát kap, ellenőrizze, hogy engedélyezve van-e a szerepköralapú hozzáférés, és hogy az identitása rendelkezik-e a szükséges szerepkör-hozzárendelésekkel.

Az alapértelmezett szolgáltató a nyilvános felhő Azure. A szuverén vagy specializált felhők egyéni audience értékei a következők:

• https://search.azure.us az Azure Government számára
• https://search.azure.cn a 21Vianet által üzemeltetett Azure
• https://search.microsoftazure.de Németországban lévő Azure számára

Helyi fejlesztés

A szerepköröket használó helyi fejlesztés az alábbi lépéseket tartalmazza:

• Rendelje hozzá személyes identitását az adott erőforrás RBAC-szerepköreihez.
• A Azure hitelesítéséhez használjon olyan eszközt, mint a Azure CLI vagy a Azure PowerShell.
• Környezeti változók létrehozása az erőforráshoz.

Szerepkörök helyi fejlesztéshez

Helyi fejlesztőként az Azure identitásának teljes körű vezérlésre van szüksége az adatsík-műveletek felett. Ezek a javasolt szerepkörök:

• Keresési szolgáltatás közreműködője, objektumok létrehozása és kezelése
• Indexadat-közreműködő keresése, index betöltése és lekérdezése, valamint tudásbázisból való lekérés

Keresse meg a személyes identitását az alábbi eszközök egyikével. Használja ezt az identitást <identity-id> értékként.

Azure CLI-

Cserélje le a helyőrzőket <role-name>, <identity-id>, <subscription-id> és <resource-group-name> a saját tényleges értékeire az alábbi parancsokban.

1. Jelentkezzen be az Azure CLI-be.

   az login
   

   Megnyílik egy böngészőablak a hitelesítéshez. A sikeres bejelentkezés után a terminál megjeleníti az előfizetés adatait.

2. Szerezze be a személyes személyazonosságát.

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

   A parancs a felhasználói objektum azonosítóját (GUID) adja vissza. Mentse ezt az értéket a következő lépéshez.

3. Rendelje hozzá a szerepköralapú hozzáférés-vezérlési (RBAC) szerepkört az erőforráscsoport identitásához.

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

   A sikeres hozzárendelés egy JSON-objektumot ad vissza a szerepkör-hozzárendelés részleteivel.

Azure PowerShell

Cserélje le a helyőrzőket <role-name>, <identity-id>, <subscription-id> és <resource-group-name> a saját tényleges értékeire az alábbi parancsokban.

1. Jelentkezzen be PowerShell-lel.

   Connect-AzAccount
   

   Megnyílik egy böngészőablak a hitelesítéshez. A sikeres bejelentkezés után a terminál megjeleníti a fiók és az előfizetés adatait.

2. Szerezze be a személyes személyazonosságát.

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

   A parancs a felhasználói objektum azonosítóját (GUID) adja vissza. Mentse ezt az értéket a következő lépéshez.

3. Rendelje hozzá a szerepköralapú hozzáférés-vezérlési (RBAC) szerepkört az erőforráscsoport identitásához.

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

   A sikeres hozzárendelés visszaadja a szerepkör-hozzárendelési objektumot a részletekkel együtt, beleértve a RoleAssignmentId.

Azure portál

1. Kövesse az itt található lépéseket: keresse meg a felhasználói objektum azonosítóját az Azure portálon.

2. Használja az szerepkör-hozzárendelés hozzáadása lapon található lépéseket az Azure portálon.

Hitelesítés helyi fejlesztéshez

Az Azure identitás hitelesítéséhez használjon eszközt a helyi fejlesztési környezetben. A hitelesítés után a DefaultAzureCredential példány a forráskódban megtalálja és a hitelesítéshez használja az Ön identitását.

Válasszon egy eszközt a hitelesítéshez a helyi fejlesztés során.

Környezeti változók konfigurálása helyi fejlesztéshez

A Azure AI Keresés való csatlakozáshoz a kódnak ismernie kell az erőforrásvégpontot.

Hozzon létre egy AZURE_SEARCH_ENDPOINT nevű környezeti változót a Azure AI Keresés végponthoz. Ennek az URL-címnek általában a formátuma https://<YOUR-RESOURCE-NAME>.search.windows.net/van.

Üzemi munkaterhelések

Az éles számítási feladatok üzembe helyezése az alábbi lépéseket tartalmazza:

• Válassza ki azokat az RBAC-szerepköröket, amelyek megfelelnek a minimális jogosultság elvének.
• RBAC-szerepkörök hozzárendelése az adott erőforrás éles identitásához.
• Környezeti változók beállítása az erőforráshoz.

Szerepkörök termelési munkaterhelésekhez

Az éles erőforrások létrehozásához először létre kell hoznia egy felhasználó által hozzárendelt felügyelt identitást, majd hozzá kell rendelnie ezt az identitást az erőforrásokhoz a megfelelő szerepkörökkel.

Éles alkalmazás esetén a következő szerepkör javasolt:

Szerepkör neve	Azonosító
Keresési index adatolvasója	1407120a-92aa-4202-b7e9-c0e197c71c8f

Hitelesítés üzemelő környezethez tartozó feladatokhoz

Az alábbi Azure AI Keresés Bicep sablon használatával hozza létre az erőforrást, és állítsa be a hitelesítést a identityId. Bicep a szerepkör-azonosítót igényli. Az ebben a Bicep kódrészletben látható name nem az Azure szerepkör, hanem a Bicep üzembe helyezésre jellemző.

// 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
    }
}

A main.bicep fájl a következő általános Bicep kódot hívja meg bármilyen szerepkör létrehozására. Több RBAC-szerepet is létrehozhat, például egyet a felhasználónak és egy másikat pedig a termelési környezetnek. Ez lehetővé teszi, hogy a fejlesztési és éles környezeteket egyazon Bicep telepítésen belül engedélyezd.

// 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)
    }
}

Környezeti változók konfigurálása éles számítási feladatokhoz

A Azure AI Keresés való csatlakozáshoz a kódnak ismernie kell az erőforrásvégpontot és a felügyelt identitás azonosítóját.

Környezeti változók létrehozása az üzembe helyezett és kulcs nélküli Azure AI Keresés erőforráshoz:

• AZURE_SEARCH_ENDPOINT: Ez az URL-cím a Azure AI Keresés erőforrás hozzáférési pontja. Ennek az URL-címnek általában a formátuma https://<YOUR-RESOURCE-NAME>.search.windows.net/van.
• AZURE_CLIENT_ID: Ez a hitelesítéshez szükséges identitás.

Gyakori hibák elhárítása

Error	Oka	Solution
AuthenticationFailedException	Hiányzó vagy érvénytelen hitelesítő adatok	Győződjön meg arról, hogy bejelentkezett a az login (CLI) vagy Connect-AzAccount a (PowerShell) szolgáltatásba. Ellenőrizze, hogy Azure fiókja rendelkezik-e hozzáféréssel az előfizetéshez.
403 Forbidden	Az identitásból hiányzik egy szükséges szerepkör	Rendelje hozzá a megfelelő szerepkört (keresési index adatolvasója lekérdezésekhez, keresési index adatszolgáltatója indexeléshez). A szerepkör-hozzárendelések propagálása akár 10 percet is igénybe vehet.
401 Unauthorized	Az RBAC nincs engedélyezve a keresési szolgáltatásban	Engedélyezze a szerepköralapú hozzáférést a Azure portálon a Settings>Keys>Role-alapú hozzáférés-vezérlés alatt.
ResourceNotFoundException	Érvénytelen végpont vagy indexnév	Ellenőrizze, hogy a AZURE_SEARCH_ENDPOINT környezeti változó megegyezik-e a keresési szolgáltatás URL-címével (formátum: https://<service-name>.search.windows.net).
CredentialUnavailableException	Nem található érvényes hitelesítő adat	DefaultAzureCredential több hitelesítési módszert is kipróbál. Győződjön meg arról, hogy legalább egy konfigurálva van (Azure CLI, Visual Studio, környezeti változók).

Kapcsolódó tartalom

• Kulcs nélküli kapcsolatok fejlesztői útmutatója
• Azure beépített szerepkörök
• Környezeti változók beállítása