Szybki start: nawiązywanie połączenia bez kluczy

Artykuł
12/20/2024

Skonfiguruj usługę Azure AI Search, aby używać uwierzytelniania identyfikatora Entra firmy Microsoft i kontroli dostępu opartej na rolach (RBAC), aby umożliwić nawiązywanie połączenia z systemu lokalnego bez kluczy interfejsu API przy użyciu notesów Jupyter lub klienta REST w celu interakcji z usługą wyszukiwania.

Jeśli przejdziesz przez inne przewodniki Szybki start, które łączą się przy użyciu kluczy interfejsu API, w tym przewodniku Szybki start pokazano, jak przełączyć się na uwierzytelnianie oparte na tożsamościach, aby uniknąć zakodowanych kluczy w przykładowym kodzie.

Wymagania wstępne

Subskrypcja platformy Azure. Utwórz je bezpłatnie.
Usługa Azure AI Search, dowolny region lub warstwa, ale musisz skonfigurować tożsamość zarządzaną dla usługi Azure AI Search w warstwie Podstawowa lub nowsza.
Narzędzie wiersza polecenia, takie jak program PowerShell lub powłoka Bash, oraz interfejs wiersza polecenia platformy Azure.

Krok 1. Pobieranie identyfikatorów subskrypcji i dzierżawy platformy Azure

Ten krok jest potrzebny, jeśli masz więcej niż jedną subskrypcję lub dzierżawę.

Pobierz subskrypcję i dzierżawę platformy Azure dla usługi wyszukiwania:
1. Zaloguj się do witryny Azure Portal i przejdź do usługi wyszukiwania.
2. Zwróć uwagę na nazwę i identyfikator subskrypcji w sekcji Przegląd>Podstawy.
3. Teraz wybierz nazwę subskrypcji, aby wyświetlić nadrzędną grupę zarządzania (identyfikator dzierżawy) na następnej stronie.
Wiesz teraz, w której subskrypcji i dzierżawie znajduje się usługa Azure AI Search. Przejdź do urządzenia lokalnego i wiersza polecenia oraz zidentyfikuj aktywną subskrypcję platformy Azure i dzierżawę na urządzeniu:
```
az account show
```
Jeśli aktywna subskrypcja i dzierżawa różnią się od informacji uzyskanych w poprzednim kroku, zmień identyfikator subskrypcji. Następnie zaloguj się do platformy Azure przy użyciu identyfikatora dzierżawy znalezionego w poprzednim kroku:
```
 az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>
```

Krok 2. Konfigurowanie funkcji RBAC w usłudze Azure AI Search

Zaloguj się do witryny Azure Portal i przejdź do usługa wyszukiwania usługi Azure AI.
Włącz kontrolę dostępu opartą na rolach (RBAC):
1. Przejdź do pozycji Klucze ustawień>.
2. Wybierz pozycję Kontrola oparta na rolach lub Obie , jeśli potrzebujesz czasu, aby przenieść klientów do kontroli dostępu opartej na rolach.
  
  Jeśli wybierzesz kontrolę opartą na rolach, upewnij się, że przypiszesz sobie wszystkie role o nazwie w następnej instrukcji lub nie będzie można wykonywać zadań w witrynie Azure Portal lub za pośrednictwem klienta lokalnego.
Przypisz role w witrynie Azure Portal:
1. Przejdź do usługi wyszukiwania.
2. Wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) w okienku nawigacji po lewej stronie.
3. Wybierz pozycję + Dodaj>Dodaj przypisanie roli.
4. Wybierz rolę (Współautor usługi wyszukiwania, Współautor danych indeksu wyszukiwania, Czytelnik danych indeksu wyszukiwania) i przypisz ją do tożsamości użytkownika lub grupy firmy Microsoft.
  
  Powtórz dla każdej roli.
  
  Potrzebujesz współautora usługi wyszukiwania oraz współautora danych indeksu wyszukiwania, aby tworzyć, ładować i wykonywać zapytania o obiekty w usłudze Azure AI Search. Aby uzyskać więcej informacji, zobacz Łączenie przy użyciu ról.

Napiwek

Później, jeśli wystąpią błędy niepowodzenia uwierzytelniania, sprawdź ponownie ustawienia w tej sekcji. Na poziomie subskrypcji lub grupy zasobów mogą istnieć zasady, które zastępują wszystkie określone ustawienia interfejsu API.

Krok 3. Nawiązywanie połączenia z systemu lokalnego

Jeśli jeszcze nie zalogowałeś się na platformie Azure:

az login

Korzystanie z notesów języka Python i programu Jupyter

Zainstaluj biblioteki tożsamości platformy Azure i usługi Azure Search:
```
pip install azure-identity azure-search-documents
```

Uwierzytelnianie i nawiązywanie połączenia z usługą Azure AI Search:

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = "https://<your-search-service-name>.search.windows.net"
index_name = "hotels-sample-index"

credential = DefaultAzureCredential()
client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

results = client.search("beach access")
for result in results:
    print(result)

Korzystanie z klienta REST

Kilka przewodników Szybki start i samouczków używa klienta REST, takiego jak Program Visual Studio Code z rozszerzeniem REST. Poniżej przedstawiono sposób nawiązywania połączenia z usługą Azure AI Search z poziomu programu Visual Studio Code.

Powinien istnieć .rest plik lub .http podobny do opisanego w przewodniku Szybki start: wyszukiwanie wektorów.

Generowanie tokenu dostępu.

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

W górnej części pliku ustaw zmienne używane dla połączenia, wklejając pełny punkt końcowy usługi wyszukiwania i token dostępu uzyskany w poprzednim kroku. Zmienne powinny wyglądać podobnie do poniższego przykładu. Zwróć uwagę, że wartości nie są ujęte w cudzysłów.
```
@baseUrl = https://contoso.search.search.windows.net
@token = <a long GUID>
```

Określ token elementu nośnego autoryzacji w wywołaniu REST:

 POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
   Content-type: application/json
   Authorization: Bearer {{token}}

     {
          "queryType": "simple",
          "search": "beach access",
          "filter": "",
          "select": "HotelName,Description,Category,Tags",
          "count": true
      }

Rozwiązywanie problemów z błędami 401

Sprawdź aktywną subskrypcję i dzierżawę (az account show) i upewnij się, że jest ona prawidłowa dla usługi wyszukiwania.
Sprawdź opcje Klucze ustawień> usługi wyszukiwania w witrynie Azure Portal i upewnij się, że usługa jest skonfigurowana dla opcji Zarówno" lub Kontrola dostępu oparta na rolach.
Tylko dla klienta REST: sprawdź token i punkt końcowy określony w pliku i upewnij się, że nie ma żadnych cudzysłowów ani dodatkowych spacji.

Jeśli wszystko inne nie powiedzie się, uruchom ponownie urządzenie, aby usunąć wszystkie buforowane tokeny, a następnie powtórz kroki opisane w tej sekcji, zaczynając od az login.

Dodatkowa konfiguracja

Skonfiguruj tożsamość zarządzaną dla połączeń wychodzących:

Skonfiguruj tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika dla usługi wyszukiwania.
Użyj przypisań ról, aby autoryzować dostęp do innych zasobów platformy Azure.

Konfiguracja dostępu do sieci:

Ustaw reguły ruchu przychodzącego, aby akceptować lub odrzucać żądania do usługi Azure AI Search na podstawie adresu IP.

Udostępnij za pośrednictwem