Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Note
Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.
W kodzie aplikacji można skonfigurować połączenie bez użycia klucza z Foundry IQ (Wyszukiwanie AI platformy Azure), które używa Microsoft Entra ID i ról na potrzeby uwierzytelniania i autoryzacji. Żądania aplikacji do większości usług Azure muszą być uwierzytelniane za pomocą kluczy lub połączeń bez kluczy. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać kluczy w niezabezpieczonej lokalizacji. Każdy, kto uzyskuje dostęp do klucza, może uwierzytelnić się w usłudze. Uwierzytelnianie bezkluczowe oferuje ulepszone korzyści w zakresie zarządzania i zabezpieczeń, ponieważ nie ma potrzeby przechowywania klucza (ani ciągu połączenia).
W tym artykule wyjaśniono, jak używać DefaultAzureCredential w kodzie aplikacji.
Aby zaimplementować połączenia bez kluczy w kodzie, wykonaj następujące kroki:
- Włącz dostęp oparty na rolach w usłudze Foundry IQ
- Ustaw zmienne środowiskowe zgodnie z potrzebami.
- Użyj typu poświadczeń biblioteki Azure Identity, aby utworzyć obiekt klienta Foundry IQ.
Wymagania wstępne
Foundry IQ, dowolny region, ale musi to być płatny plan (podstawowy lub wyższy).
Włączono dostęp oparty na rolach w usłudze Foundry IQ.
Przypisania ról w usłudze Foundry IQ. Przypisz te role do swojej tożsamości:
- Search Service Contributor i Search Index Data Contributor na potrzeby programowania lokalnego (pełny dostęp)
- Search Index Data Reader na potrzeby produkcyjnych zapytań tylko do odczytu
Aby uzyskać instrukcje krok po kroku, zobacz Przypisywanie ról do programowania.
Instalowanie biblioteki klienta Azure Identity
Aby użyć podejścia bez klucza, zaktualizuj kod z obsługą Foundry IQ przy użyciu biblioteki klienta Azure Identity.
Zainstaluj bibliotekę klienta Azure Identity dla .NET i bibliotekę klienta Azure Search Documents:
dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents
Zaktualizuj kod źródłowy, aby używać DefaultAzureCredential.
Biblioteka Azure Identity DefaultAzureCredential umożliwia uruchamianie tego samego kodu w lokalnym środowisku projektowym i w chmurze Azure. Utwórz pojedyncze poświadczenie i ponownie skorzystaj z instancji poświadczenia w razie potrzeby, aby skorzystać z buforowania tokenów.
Aby uzyskać więcej informacji na temat DefaultAzureCredential dla platformy .NET, zobacz Azure Identity client library for .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);
Odwołanie:SearchClient, SearchIndexClient, DefaultAzureCredential
Weryfikowanie połączenia
Po skonfigurowaniu klienta sprawdź połączenie, uruchamiając prostą operację. Poniższy przykład wyświetla indeksy w usłudze Foundry IQ:
// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
Console.WriteLine(name);
}
Udane połączenie wyświetla nazwy indeksów (lub pustą listę, jeśli nie istnieją żadne indeksy). Jeśli wystąpi błąd uwierzytelniania, sprawdź, czy dostęp oparty na rolach jest włączony, a Twoja tożsamość ma przypisane wymagane role.
Domyślnym urzędem jest Azure chmura publiczna. Niestandardowe audience wartości dla chmur suwerennych lub wyspecjalizowanych obejmują:
-
https://search.azure.usdla Azure Government -
https://search.azure.cndla Azure obsługiwanego przez firmę 21Vianet -
https://search.microsoftazure.dedla Azure Germany
Rozwój lokalny
Programowanie lokalne przy użyciu ról obejmuje następujące kroki:
- Przypisz tożsamość osobistą do ról RBAC w określonym zasobie.
- Użyj narzędzia, takiego jak Azure CLI lub Azure PowerShell, aby uwierzytelnić się za pomocą Azure.
- Ustaw zmienne środowiskowe dla zasobu.
Role na potrzeby rozwoju lokalnego
Jako lokalny deweloper, Twoja tożsamość Azure musi mieć pełną kontrolę nad operacjami płaszczyzny danych. Są to sugerowane role:
- Współautor usługi wyszukiwania, tworzenie obiektów i zarządzanie nimi
- Współautor danych indeksu wyszukiwania, ładowanie i wykonywanie zapytań względem indeksu oraz pobieranie ich z bazy wiedzy
Znajdź swoją tożsamość osobistą przy użyciu jednego z następujących narzędzi. Użyj tej tożsamości jako <identity-id> wartości.
Zastąp elementy zastępcze <role-name>, <identity-id>, <subscription-id> i <resource-group-name> rzeczywistymi wartościami w następujących poleceniach.
Zaloguj się do Azure CLI.
az loginZostanie otwarte okno przeglądarki na potrzeby uwierzytelniania. Po pomyślnym zalogowaniu w terminalu zostaną wyświetlone informacje o subskrypcji.
Uzyskaj tożsamość osobistą.
az ad signed-in-user show \ --query id -o tsvPolecenie zwraca identyfikator obiektu użytkownika (GUID). Zapisz tę wartość dla następnego kroku.
Przypisz rolę kontroli dostępu opartej na rolach (RBAC) do tożsamości grupy zasobów.
az role assignment create \ --role "<role-name>" \ --assignee "<identity-id>" \ --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"Pomyślne przypisanie zwraca obiekt JSON ze szczegółami przypisania roli.
Uwierzytelnianie na potrzeby programowania lokalnego
Użyj narzędzia w lokalnym środowisku projektowym do uwierzytelniania względem tożsamości Azure. Gdy jesteś uwierzytelniony, wystąpienie DefaultAzureCredential w kodzie źródłowym znajduje i używa Twojej tożsamości do celów uwierzytelniania.
Wybierz narzędzie do uwierzytelniania podczas programowania lokalnego.
Konfigurowanie zmiennych środowiskowych na potrzeby programowania lokalnego
Aby nawiązać połączenie z Foundry IQ, kod musi znać punkt końcowy zasobu.
Utwórz zmienną środowiskową o nazwie AZURE_SEARCH_ENDPOINT dla punktu końcowego Foundry IQ. Ten adres URL ma zazwyczaj format https://<YOUR-RESOURCE-NAME>.search.windows.net/.
Obciążenia produkcyjne
Wdrażanie obciążeń produkcyjnych obejmuje następujące kroki:
- Wybierz role RBAC, które są zgodne z zasadą minimalnych uprawnień.
- Przypisz role RBAC do tożsamości produkcyjnej dla określonego zasobu.
- Skonfiguruj zmienne środowiskowe dla zasobu.
Role dla obciążeń produkcyjnych
Aby utworzyć zasoby produkcyjne, należy utworzyć tożsamość zarządzaną przypisaną przez użytkownika , a następnie przypisać jej tożsamość do zasobów przy użyciu odpowiednich ról.
W przypadku aplikacji produkcyjnej sugerowana jest następująca rola:
| Nazwa roli | Id |
|---|---|
| Czytnik danych indeksu wyszukiwania | 1407120a-92aa-4202-b7e9-c0e197c71c8f |
Uwierzytelnianie dla obciążeń produkcyjnych
Użyj następującego szablonu Bicep Foundry IQ, aby utworzyć zasób i ustawić konfigurację uwierzytelniania dla elementu identityId. Bicep wymaga identyfikatora roli.
name pokazany w tym fragmencie kodu Bicep nie jest rolą Azure; jest specyficzna dla wdrożenia 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
}
}
Plik main.bicep wywołuje następujący ogólny kod Bicep, aby utworzyć dowolną rolę. Istnieje możliwość utworzenia wielu ról RBAC, takich jak jedna dla użytkownika, a druga dla środowiska produkcyjnego. Umożliwia to włączenie zarówno środowisk deweloperskich, jak i produkcyjnych w ramach tego samego wdrożenia 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)
}
}
Konfigurowanie zmiennych środowiskowych dla obciążeń produkcyjnych
Aby połączyć się z Foundry IQ, kod musi znać adres punktu końcowego zasobu oraz identyfikator tożsamości zarządzanej.
Utwórz zmienne środowiskowe dla wdrożonego i bezkluczowego zasobu Foundry IQ:
-
AZURE_SEARCH_ENDPOINT: ten adres URL jest punktem dostępu dla zasobu IQ usługi Foundry. Ten adres URL ma zazwyczaj formathttps://<YOUR-RESOURCE-NAME>.search.windows.net/. -
AZURE_CLIENT_ID: Jest to tożsamość używana do uwierzytelniania.
Rozwiązywanie typowych błędów
| Error | Przyczyna | Rozwiązanie |
|---|---|---|
AuthenticationFailedException |
Brakujące lub nieprawidłowe poświadczenia | Upewnij się, że jesteś zalogowany/a przy użyciu az login (CLI - interfejs wiersza polecenia) lub Connect-AzAccount (PowerShell). Sprawdź, czy konto Azure ma dostęp do subskrypcji. |
403 Forbidden |
Tożsamość nie ma wymaganej roli | Przypisz odpowiednią rolę (Czytelnik danych indeksu wyszukiwania dla zapytań, Współautor danych indeksu wyszukiwania na potrzeby indeksowania). Propagacja przypisań ról może potrwać do 10 minut. |
401 Unauthorized |
RBAC nie jest włączony w usłudze Foundry IQ | Włącz dostęp oparty na rolach w portalu Azure w obszarze Settings>Keys>Kontrola dostępu oparta na rolach. |
ResourceNotFoundException |
Nieprawidłowa nazwa punktu końcowego lub indeksu | Sprawdź, czy zmienna środowiskowa AZURE_SEARCH_ENDPOINT odpowiada adresowi URL usługi Foundry IQ (format: https://<service-name>.search.windows.net). |
CredentialUnavailableException |
Nie znaleziono prawidłowych poświadczeń |
DefaultAzureCredential próbuje wielu metod uwierzytelniania. Upewnij się, że skonfigurowano co najmniej jedno (Azure CLI, Visual Studio, zmienne środowiskowe). |