Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról

Platforma Azure zapewnia globalne uwierzytelnianie i kontrolę dostępu opartą na rolach za pośrednictwem identyfikatora Entra firmy Microsoft dla wszystkich usług uruchomionych na platformie. W tym artykule dowiesz się, które role zapewniają dostęp do wyszukiwania zawartości i administracji w usłudze Azure AI Search.

W usłudze Azure AI Search można przypisać role platformy Azure dla:

• Administrowanie usługą
• Tworzenie lub zapisywanie dostępu do usługi wyszukiwania
• Dostęp tylko do odczytu dla zapytań
• Dostęp o określonym zakresie do pojedynczego indeksu

Dostęp poszczególnych użytkowników za pośrednictwem wyników wyszukiwania (czasami nazywanych zabezpieczeniami na poziomie wiersza lub zabezpieczeniami na poziomie dokumentu) nie jest obsługiwany za pośrednictwem przypisań ról. Aby obejść ten problem, utwórz filtry zabezpieczeń, które przycinają wyniki według tożsamości użytkownika, usuwając dokumenty, dla których żądający nie powinien mieć dostępu. Zobacz ten przykład czatu dla przedsiębiorstw przy użyciu programu RAG , aby zapoznać się z pokazem.

Przypisania ról są skumulowane i wszechobecne we wszystkich narzędziach i bibliotekach klienckich. Role można przypisywać przy użyciu dowolnej z obsługiwanych metod opisanych w dokumentacji kontroli dostępu opartej na rolach platformy Azure.

Dostęp oparty na rolach jest opcjonalny, ale zalecany. Alternatywą jest uwierzytelnianie oparte na kluczach, czyli domyślne.

Wymagania wstępne

• Usługa wyszukiwania w dowolnym regionie, w dowolnej warstwie, włączona na potrzeby dostępu opartego na rolach.

• Właściciel, administrator dostępu użytkowników, administrator kontroli dostępu opartej na rolach lub rola niestandardowa z uprawnieniami Microsoft.Authorization/roleAssignments/write .

Jak przypisywać role w portalu

Poniższe kroki działają dla wszystkich przypisań ról.

1. Zaloguj się w witrynie Azure Portal.

2. Przejdź do usługi wyszukiwania.

3. Włącz dostęp oparty na rolach.

4. Wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) w okienku nawigacji po lewej stronie.

5. Wybierz pozycję + Dodaj>przypisanie roli, aby uruchomić Kreatora dodawania przypisania roli.

   

6. Wybierz rolę. Można przypisać wiele podmiotów zabezpieczeń, niezależnie od tego, czy użytkownicy, czy tożsamości zarządzane do roli w jednym przekazaniu kreatora, ale musisz powtórzyć te kroki dla każdej zdefiniowanej roli.

7. Na karcie Członkowie wybierz tożsamość użytkownika lub grupy firmy Microsoft Entra. Jeśli konfigurujesz uprawnienia dla innej usługi platformy Azure, wybierz tożsamość systemową lub zarządzaną przez użytkownika.

8. Na karcie Przeglądanie i przypisywanie wybierz pozycję Przejrzyj i przypisz, aby przypisać rolę.

Wbudowane role używane w wyszukiwaniu

Płaszczyzna danych odnosi się do operacji względem punktu końcowego usługi wyszukiwania, takiego jak indeksowanie lub zapytania, lub dowolna inna operacja określona w interfejsach API REST usługi wyszukiwania lub równoważne biblioteki klienta zestawu Azure SDK.

Płaszczyzna sterowania odnosi się do zarządzania zasobami platformy Azure, takich jak tworzenie lub konfigurowanie usługi wyszukiwania.

Następujące role są wbudowane. Jeśli te role są niewystarczające, utwórz rolę niestandardową.

Rola	Płaszczyzna	opis
Właściciel	Kontrolka i dane	Pełny dostęp do płaszczyzny sterowania zasobu wyszukiwania, w tym możliwość przypisywania ról platformy Azure. Tylko rola Właściciel może włączać lub wyłączać opcje uwierzytelniania lub zarządzać rolami dla innych użytkowników. Administratorzy subskrypcji są domyślnie członkami. Na płaszczyźnie danych ta rola ma taki sam dostęp jak rola Współautor usługi wyszukiwania. Obejmuje ona dostęp do wszystkich akcji płaszczyzny danych z wyjątkiem możliwości wykonywania zapytań lub indeksowania dokumentów.
Współautor	Kontrolka i dane	Ten sam poziom dostępu płaszczyzny kontroli co Właściciel, minus możliwość przypisywania ról lub zmiany opcji uwierzytelniania. Na płaszczyźnie danych ta rola ma taki sam dostęp jak rola Współautor usługi wyszukiwania. Obejmuje ona dostęp do wszystkich akcji płaszczyzny danych z wyjątkiem możliwości wykonywania zapytań lub indeksowania dokumentów.
Czytelnik	Kontrolka i dane	Dostęp do odczytu w całej usłudze, w tym metryki wyszukiwania, metryki zawartości (wykorzystany magazyn, liczba obiektów) oraz definicje obiektów zasobów płaszczyzny danych (indeksy, indeksatory itd.). Nie może jednak odczytywać kluczy interfejsu API ani odczytywać zawartości w indeksach.
Współautor usługi wyszukiwania	Kontrolka i dane	Dostęp do odczytu i zapisu do definicji obiektów (indeksy, aliasy, mapy synonimów, indeksatory, źródła danych i zestawy umiejętności). Ta rola dotyczy deweloperów, którzy tworzą obiekty, oraz administratorów, którzy zarządzają usługą wyszukiwania i jej obiektami, ale bez dostępu do zawartości indeksu. Ta rola służy do tworzenia, usuwania i wyświetlania indeksów, pobierania definicji indeksów, pobierania informacji o usłudze (statystyk i przydziałów), analizatorów testów, tworzenia map synonimów, indeksatorów, źródeł danych i zestawów umiejętności oraz zarządzania nimi. Zobacz Microsoft.Search/searchServices/* listę uprawnień.
Współautor danych indeksu wyszukiwania	Data	Dostęp do odczytu i zapisu do zawartości w indeksach. Ta rola jest dla deweloperów lub właścicieli indeksów, którzy muszą importować, odświeżać lub wykonywać zapytania dotyczące kolekcji dokumentów indeksu. Ta rola nie obsługuje tworzenia indeksów ani zarządzania nimi. Domyślnie ta rola dotyczy wszystkich indeksów w usłudze wyszukiwania. Zobacz Udzielanie dostępu do pojedynczego indeksu , aby zawęzić zakres.
Czytnik danych indeksu wyszukiwania	Data	Dostęp tylko do odczytu na potrzeby wykonywania zapytań dotyczących indeksów wyszukiwania. Ta rola dotyczy aplikacji i użytkowników, którzy uruchamiają zapytania. Ta rola nie obsługuje dostępu do odczytu do definicji obiektów. Na przykład nie można odczytać definicji indeksu wyszukiwania ani pobrać statystyk usługi wyszukiwania. Domyślnie ta rola dotyczy wszystkich indeksów w usłudze wyszukiwania. Zobacz Udzielanie dostępu do pojedynczego indeksu , aby zawęzić zakres.

Połącz te role, aby uzyskać wystarczające uprawnienia dla twojego przypadku użycia.

Uwaga

Jeśli wyłączysz dostęp oparty na rolach platformy Azure, wbudowane role dla płaszczyzny sterowania (właściciel, współautor, czytelnik) będą nadal dostępne. Wyłączenie dostępu opartego na rolach spowoduje usunięcie tylko uprawnień związanych z danymi skojarzonych z tymi rolami. Jeśli role płaszczyzny danych są wyłączone, współautor usługi wyszukiwania jest odpowiednikiem współautora płaszczyzny sterowania.

Podsumowanie

Uprawnienia	Czytnik danych indeksu wyszukiwania	Współautor danych indeksu wyszukiwania	Współautor usługi wyszukiwania	Właściciel/współautor	Czytelnik
Wyświetlanie zasobu w witrynie Azure Portal	❌	❌	✅	✅	✅
Wyświetlanie właściwości zasobu/metryk/punktu końcowego	❌	❌	✅	✅	✅
Wyświetlanie listy wszystkich obiektów w zasobie	❌	❌	✅	✅	✅
Limity przydziału dostępu i statystyki usługi	❌	❌	✅	✅	❌
Odczytywanie/wykonywanie zapytań względem indeksu	✅	❌	❌	❌	❌
Przekazywanie danych do indeksowania	❌	✅	❌	❌	❌
Tworzenie lub edytowanie indeksów/aliasów	❌	❌	✅	✅	❌
Tworzenie, edytowanie i uruchamianie indeksatorów/źródeł danych/zestawów umiejętności	❌	❌	✅	✅	❌
Tworzenie lub edytowanie map synonimów	❌	❌	✅	✅	❌
Tworzenie lub edytowanie sesji debugowania	❌	❌	✅	✅	❌
Tworzenie wdrożeń lub zarządzanie nimi	❌	❌	✅	✅	❌
Tworzenie lub konfigurowanie zasobów usługi Azure AI Search	❌	❌	✅	✅	❌
Wyświetlanie/kopiowanie/ponowne generowanie kluczy w obszarze Klucze	❌	❌	✅	✅	❌
Wyświetlanie ról/zasad/definicji	❌	❌	✅	✅	❌
Ustawianie opcji uwierzytelniania	❌	❌	✅	✅	❌
Konfigurowanie połączeń prywatnych	❌	❌	✅	✅	❌
Konfigurowanie zabezpieczeń sieci	❌	❌	✅	✅	❌

Właściciele i współautorzy przyznają te same uprawnienia, z wyjątkiem tego, że tylko właściciele mogą przypisywać role.

Właściciele i współautorzy mogą tworzyć, odczytywać, aktualizować i usuwać obiekty w witrynie Azure Portal , jeśli są włączone klucze interfejsu API. Portal używa kluczy w wywołaniach wewnętrznych do interfejsów API płaszczyzny danych. Następnie skonfigurujesz usługę Azure AI Search tak, aby korzystała tylko z ról, a następnie właściciel i współautor nie będą mogli zarządzać obiektami w portalu przy użyciu tylko tych przypisań ról. Rozwiązaniem jest przypisanie większej liczby ról, takich jak czytelnik danych indeksu wyszukiwania, współautor danych indeksu wyszukiwania i współautor usługi wyszukiwania.

Przypisywanie ról

W tej sekcji przypisz role dla:

• Administrowanie usługą
• Tworzenie lub zapisywanie dostępu do usługi wyszukiwania
• Dostęp tylko do odczytu dla zapytań

Przypisywanie ról do administrowania usługą

Jako administrator usługi możesz utworzyć i skonfigurować usługę wyszukiwania oraz wykonać wszystkie operacje płaszczyzny sterowania opisane w interfejsie API REST zarządzania lub równoważnych bibliotekach klienckich. Jeśli jesteś właścicielem lub współautorem, możesz również wykonywać większość zadań interfejsu API REST wyszukiwania płaszczyzny danych w witrynie Azure Portal.

Rola	ID
Owner	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor	b24988ac-6180-42a0-ab88-20f7382dd24c
Reader	acdd72a7-3385-48ef-bd42-f606fba81ae7

Witryna Azure Portal

1. Zaloguj się w witrynie Azure Portal.

2. Przypisz następujące role:

   • Właściciel (pełny dostęp do wszystkich operacji płaszczyzny danych i płaszczyzny sterowania, z wyjątkiem uprawnień zapytania)
   • Współautor (taki sam jak właściciel, z wyjątkiem uprawnień do przypisywania ról)
   • Czytelnik (akceptowalny w przypadku monitorowania i wyświetlania metryk)

Program PowerShell

W przypadku przypisywania ról przy użyciu programu PowerShell wywołaj polecenie New-AzRoleAssignment, podając nazwę użytkownika lub grupy platformy Azure oraz zakres przypisania.

W tym przykładzie utworzono przypisanie roli o zakresie do usługi wyszukiwania:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Przypisywanie ról do programowania

Przypisania ról są globalne w całej usłudze wyszukiwania. Aby ograniczyć zakres uprawnień do pojedynczego indeksu, użyj programu PowerShell lub interfejsu wiersza polecenia platformy Azure, aby utworzyć rolę niestandardową.

Zadanie	Rola	ID
Operacje CRUD	Search Service Contributor	7ca78c08-252a-4471-8644-bb5ff32d4ba0
Ładowanie dokumentów, uruchamianie zadań indeksowania	Search Index Data Contributor	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Wykonywanie zapytań względem indeksu	Search Index Data Reader	1407120a-92aa-4202-b7e9-c0e197c71c8f

Inną kombinacją ról, które zapewniają pełny dostęp, jest Współautor lub Właściciel oraz Czytelnik danych indeksu wyszukiwania.

Ważne

W przypadku skonfigurowania dostępu opartego na rolach dla usługi lub indeksu i podania klucza interfejsu API w żądaniu usługa wyszukiwania używa klucza interfejsu API do uwierzytelniania.

Witryna Azure Portal

1. Zaloguj się w witrynie Azure Portal.

2. Przypisz następujące role:

   • Współautor usługi wyszukiwania (operacje create-read-update-delete na indeksach, indeksatorach, zestawach umiejętności i innych obiektach najwyższego poziomu)
   • Współautor danych indeksu wyszukiwania (ładowanie dokumentów i uruchamianie zadań indeksowania)
   • Czytnik danych indeksu wyszukiwania (wykonywanie zapytań względem indeksu)

Program PowerShell

W przypadku przypisywania ról przy użyciu programu PowerShell wywołaj polecenie New-AzRoleAssignment, podając nazwę użytkownika lub grupy platformy Azure oraz zakres przypisania.

W tym przykładzie utworzono przypisanie roli o zakresie do usługi wyszukiwania:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

W tym przykładzie utworzono przypisanie roli o określonym zakresie do określonego indeksu:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Przypisywanie ról dla zapytań tylko do odczytu

Użyj roli Czytelnik danych indeksu wyszukiwania dla aplikacji i procesów, które wymagają tylko dostępu do odczytu do indeksu.

Rola	ID
Search Index Data Readerza pomocą programu PowerShell	1407120a-92aa-4202-b7e9-c0e197c71c8f

Jest to bardzo konkretna rola. Zapewnia dostęp GET lub POST do kolekcji dokumentów indeksu wyszukiwania na potrzeby wyszukiwania, autouzupełniania i sugestii. Nie obsługuje operacji GET lub LIST na indeksie lub innych obiektach najwyższego poziomu ani statystyk usługi GET.

Ta sekcja zawiera podstawowe kroki konfigurowania przypisania roli i znajduje się tutaj na potrzeby kompletności, ale zalecamy używanie usługi Azure AI Search bez kluczy , aby uzyskać kompleksowe instrukcje dotyczące konfigurowania aplikacji na potrzeby dostępu opartego na rolach.

Witryna Azure Portal

1. Zaloguj się w witrynie Azure Portal.

2. Przypisz rolę Czytelnik danych indeksu wyszukiwania.

Program PowerShell

W przypadku przypisywania ról przy użyciu programu PowerShell wywołaj polecenie New-AzRoleAssignment, podając nazwę użytkownika lub grupy platformy Azure oraz zakres przypisania.

1. Pobierz identyfikator subskrypcji, grupę zasobów usługi wyszukiwania i nazwę usługi wyszukiwania.

2. Pobierz identyfikator obiektu usługi platformy Azure, taki jak Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Pobierz definicję roli i przejrzyj uprawnienia, aby upewnić się, że jest to odpowiednia rola.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Utwórz przypisanie roli, podstawiając prawidłowe wartości dla symboli zastępczych.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. Oto przykład przypisania roli o określonym zakresie do określonego indeksu:

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

Testowanie przypisań ról

Użyj klienta do testowania przypisań ról. Należy pamiętać, że role są rolami zbiorczych i dziedziczonych, które są ograniczone do poziomu subskrypcji lub grupy zasobów, nie można usunąć ani odmówić na poziomie zasobu (usługi wyszukiwania).

Przed rozpoczęciem testowania skonfiguruj aplikację pod kątem połączeń bez kluczy i przypisań ról.

Witryna Azure Portal

1. Zaloguj się w witrynie Azure Portal.

2. Przejdź do usługi wyszukiwania.

3. Na stronie Przegląd wybierz kartę Indeksy :

   • Współautorzy usługi wyszukiwania mogą wyświetlać i tworzyć dowolny obiekt, ale nie mogą ładować dokumentów ani wykonywać zapytań dotyczących indeksu. Aby zweryfikować uprawnienia, utwórz indeks wyszukiwania.

   • Współautorzy danych indeksu wyszukiwania mogą ładować dokumenty. W portalu nie ma opcji ładowania dokumentów poza kreatorem importu danych, ale możesz zresetować i uruchomić indeksator, aby potwierdzić uprawnienia do ładowania dokumentu.

   • Czytelnicy danych indeksu wyszukiwania mogą wykonywać zapytania dotyczące indeksu. Aby zweryfikować uprawnienia, użyj Eksploratora wyszukiwania. Powinno być możliwe wysyłanie zapytań i wyświetlanie wyników, ale nie powinno być możliwe wyświetlenie definicji indeksu ani utworzenie go.

Interfejs API REST

W tym podejściu przyjęto założenie, że program Visual Studio Code z rozszerzeniem klienta REST.

1. Otwórz powłokę poleceń dla interfejsu wiersza polecenia platformy Azure i zaloguj się do subskrypcji platformy Azure.

   az login
   

2. Pobierz identyfikator dzierżawy i identyfikator subskrypcji. Identyfikator jest używany jako zmienna w przyszłym kroku.

   az account show
   

3. Uzyskiwanie tokenu dostępu.

   az account get-access-token --query accessToken --output tsv
   

4. Wklej te zmienne w nowym pliku tekstowym w programie Visual Studio Code.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Wklej i wyślij żądanie, które używa określonych zmiennych. Dla roli "Czytelnik danych indeksu wyszukiwania" możesz wysłać zapytanie. Możesz użyć dowolnej obsługiwanej wersji interfejsu API.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Aby uzyskać więcej informacji na temat uzyskiwania tokenu dla określonego środowiska, zobacz Manage a Azure AI usługa wyszukiwania with REST APIs and Platforma tożsamości Microsoft authentication libraries (Zarządzanie usługą Azure AI usługa wyszukiwania przy użyciu interfejsów API REST i bibliotek uwierzytelniania Platforma tożsamości Microsoft).

.NET

1. Użyj pakietu Azure.Search.Documents.

2. Użyj usługi Azure.Identity dla platformy .NET na potrzeby uwierzytelniania tokenu. Firma Microsoft zaleca DefaultAzureCredential() korzystanie z większości scenariuszy.

3. Oto przykład połączenia klienta przy użyciu polecenia DefaultAzureCredential().

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. Oto kolejny przykład użycia poświadczeń wpisu tajnego klienta:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

Python

1. Użyj azure.search.documents (zestaw Azure SDK dla języka Python).

2. Użyj usługi Azure.Identity dla języka Python na potrzeby uwierzytelniania tokenów.

3. Użyj wartości DefaultAzureCredential , jeśli klient języka Python jest aplikacją, która wykonuje po stronie serwera. Włącz uwierzytelnianie interakcyjne, jeśli aplikacja działa w przeglądarce.

4. Oto przykład:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

JavaScript

1. Użyj @azure/search-documents (Zestaw Azure SDK dla języka JavaScript), wersja 11.3.

2. Użyj usługi Azure.Identity dla języka JavaScript na potrzeby uwierzytelniania tokenu.

3. Jeśli używasz platformy React, użyj InteractiveBrowserCredential uwierzytelniania Microsoft Entra do wyszukiwania. Zobacz Kiedy używać @azure/identity , aby uzyskać szczegółowe informacje.

Java

1. Użyj usługi azure-search-documents (zestawu Azure SDK dla języka Java).

2. Użyj elementu Azure.Identity dla języka Java na potrzeby uwierzytelniania tokenu.

3. Firma Microsoft zaleca ustawienie DefaultAzureCredential dla aplikacji uruchamianych na platformie Azure.

Testowanie jako bieżący użytkownik

Jeśli jesteś już współautorem lub właścicielem usługi wyszukiwania, możesz przedstawić token elementu nośnego dla tożsamości użytkownika na potrzeby uwierzytelniania w usłudze Azure AI Search.

1. Pobierz token elementu nośnego dla bieżącego użytkownika przy użyciu interfejsu wiersza polecenia platformy Azure:

   az account get-access-token --scope https://search.azure.com/.default
   

   Lub przy użyciu programu PowerShell:

   Get-AzAccessToken -ResourceUrl https://search.azure.com
   

2. Wklej te zmienne do nowego pliku tekstowego w programie Visual Studio Code.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

3. Wklej polecenie , a następnie wyślij żądanie, aby potwierdzić dostęp. Oto jeden, który wykonuje zapytania dotyczące indeksu hotels-quickstart

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Udzielanie dostępu do pojedynczego indeksu

W niektórych scenariuszach możesz ograniczyć dostęp aplikacji do pojedynczego zasobu, takiego jak indeks.

Portal nie obsługuje obecnie przypisań ról na tym poziomie szczegółowości, ale można to zrobić za pomocą programu PowerShell lub interfejsu wiersza polecenia platformy Azure.

W programie PowerShell użyj polecenia New-AzRoleAssignment, podając nazwę użytkownika lub grupy platformy Azure oraz zakres przypisania.

1. Załaduj Azure moduły i AzureAD i połącz się z kontem platformy Azure:

   Import-Module -Name Az
   Import-Module -Name AzureAD
   Connect-AzAccount
   

2. Dodaj przypisanie roli o zakresie do pojedynczego indeksu:

   New-AzRoleAssignment -ObjectId <objectId> `
       -RoleDefinitionName "Search Index Data Contributor" `
       -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
   

Tworzenie roli niestandardowej

Jeśli wbudowane role nie zapewniają odpowiedniej kombinacji uprawnień, możesz utworzyć rolę niestandardową do obsługi wymaganych operacji.

W tym przykładzie klonuje czytnik danych indeksu wyszukiwania, a następnie dodaje możliwość wyświetlania listy indeksów według nazwy. Zwykle wyświetlanie indeksów w usłudze wyszukiwania jest uznawane za prawo administracyjne.

Azure Portal

Te kroki pochodzą z sekcji Tworzenie lub aktualizowanie ról niestandardowych platformy Azure przy użyciu witryny Azure Portal. Klonowanie z istniejącej roli jest obsługiwane na stronie usługi wyszukiwania.

Te kroki tworzą rolę niestandardową, która rozszerza prawa zapytań wyszukiwania w celu uwzględnienia indeksów listy według nazwy. Zazwyczaj lista indeksów jest traktowana jako funkcja administracyjna.

1. W witrynie Azure Portal przejdź do usługi wyszukiwania.

2. W okienku nawigacji po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).

3. Na pasku akcji wybierz pozycję Role.

4. Kliknij prawym przyciskiem myszy pozycję Search Index Data Reader (lub inną rolę) i wybierz polecenie Clone (Klonuj ), aby otworzyć kreatora Tworzenie roli niestandardowej.

5. Na karcie Podstawy podaj nazwę roli niestandardowej, na przykład "Search Index Data Explorer", a następnie wybierz przycisk Dalej.

6. Na karcie Uprawnienia wybierz pozycję Dodaj uprawnienie.

7. Na karcie Dodawanie uprawnień wyszukaj, a następnie wybierz kafelek Microsoft Search .

8. Ustaw uprawnienia dla roli niestandardowej. W górnej części strony użyj domyślnego wyboru Akcje :

   • W obszarze Microsoft.Search/operations wybierz pozycję Odczyt: Wyświetl wszystkie dostępne operacje.
   • W obszarze Microsoft.Search/searchServices/indexes wybierz pozycję Odczyt: Odczyt indeksu.

9. Na tej samej stronie przejdź do pozycji Akcje danych i w obszarze Microsoft.Search/searchServices/indexes/documents wybierz pozycję Odczyt: Odczytaj dokumenty.

   Definicja JSON wygląda podobnie do poniższego przykładu:

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. Wybierz pozycję Przejrzyj i utwórz , aby utworzyć rolę. Teraz możesz przypisać użytkowników i grupy do roli.

Azure PowerShell

W przykładzie programu PowerShell przedstawiono składnię JSON do tworzenia roli niestandardowej, która jest klonem czytnika danych indeksu wyszukiwania, ale z możliwością wyświetlania listy wszystkich indeksów według nazwy.

1. Przejrzyj listę niepodzielnych uprawnień, aby określić, które z nich potrzebujesz. W tym przykładzie potrzebne są następujące elementy:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Skonfiguruj sesję programu PowerShell, aby utworzyć rolę niestandardową. Aby uzyskać szczegółowe instrukcje, zobacz Azure PowerShell

3. Podaj definicję roli jako dokument JSON. Poniższy przykład przedstawia składnię tworzenia roli niestandardowej za pomocą programu PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Uwaga

Jeśli zakres możliwy do przypisania znajduje się na poziomie indeksu, akcja danych powinna mieć wartość "Microsoft.Search/searchServices/indexes/documents/read".

Interfejs API REST

1. Przejrzyj listę niepodzielnych uprawnień, aby określić, które z nich potrzebujesz.

2. Aby uzyskać instrukcje, zobacz Tworzenie lub aktualizowanie ról niestandardowych platformy Azure przy użyciu interfejsu API REST.

3. Skopiuj lub utwórz rolę albo użyj formatu JSON, aby określić rolę niestandardową (zobacz kartę programu PowerShell dla składni JSON).

Interfejs wiersza polecenia platformy Azure

1. Przejrzyj listę niepodzielnych uprawnień, aby określić, które z nich potrzebujesz.

2. Aby uzyskać instrukcje, zobacz Tworzenie lub aktualizowanie ról niestandardowych platformy Azure przy użyciu interfejsu wiersza polecenia platformy Azure.

3. Zobacz kartę programu PowerShell, aby zapoznać się ze składnią JSON.

Dostęp warunkowy

Zalecamy dostęp warunkowy firmy Microsoft Entra, jeśli musisz wymusić zasady organizacji, takie jak uwierzytelnianie wieloskładnikowe.

Aby włączyć zasady dostępu warunkowego dla usługi Azure AI Search, wykonaj następujące kroki:

1. Zaloguj się do witryny Azure Portal.

2. Wyszukaj pozycję Dostęp warunkowy firmy Microsoft Entra.

3. Wybierz pozycję Zasady.

4. Wybierz pozycję Nowe zasady.

5. W sekcji Aplikacje w chmurze lub akcje zasad dodaj usługę Azure AI Search jako aplikację w chmurze w zależności od sposobu konfigurowania zasad.

6. Zaktualizuj pozostałe parametry zasad. Na przykład określ użytkowników i grupy, do których mają zastosowanie te zasady.

7. Zapisz zasady.

Ważne

Jeśli usługa wyszukiwania ma przypisaną tożsamość zarządzaną, określona usługa wyszukiwania będzie wyświetlana jako aplikacja w chmurze, która może zostać dołączona lub wykluczona w ramach zasad dostępu warunkowego. Nie można wymusić zasad dostępu warunkowego w określonej usłudze wyszukiwania. Zamiast tego upewnij się, że wybrano ogólną aplikację usługi Azure AI Search w chmurze.

Ograniczenia

• Kontrola dostępu oparta na rolach może zwiększyć opóźnienie niektórych żądań. Każda unikatowa kombinacja zasobu usługi (indeks, indeksator itp.) i jednostka usługi wyzwala sprawdzanie autoryzacji. Te kontrole autoryzacji mogą składać się z maksymalnie 200 milisekund opóźnienia na żądanie.

• W rzadkich przypadkach, w których żądania pochodzą z dużej liczby różnych jednostek usługi, wszystkie przeznaczone dla różnych zasobów usługi (indeksy, indeksatory itp.), możliwe jest sprawdzenie autoryzacji w celu ograniczenia przepustowości. Ograniczanie przepustowości miałoby miejsce tylko wtedy, gdy w ciągu sekundy użyto setek unikatowych kombinacji zasobu usługi wyszukiwania i jednostki usługi.

Rozwiązywanie problemów z kontrolą dostępu opartą na rolach

Podczas tworzenia aplikacji korzystających z kontroli dostępu opartej na rolach do uwierzytelniania mogą wystąpić niektóre typowe problemy:

• Jeśli token autoryzacji pochodzi z tożsamości zarządzanej i zostały niedawno przypisane odpowiednie uprawnienia, może upłynąć kilka godzin, aby te przypisania uprawnień zaczęły obowiązywać.

• Domyślną konfiguracją usługi wyszukiwania jest uwierzytelnianie oparte na kluczach. Jeśli ustawienie klucza domyślnego nie zostało zmienione na Zarówno , jak i Kontrola dostępu oparta na rolach, wszystkie żądania korzystające z uwierzytelniania opartego na rolach są automatycznie odrzucane niezależnie od podstawowych uprawnień.