Szybki start: nawiązywanie połączenia z usługą wyszukiwania

W tym szybkim przewodniku użyjesz kontroli dostępu opartej na rolach (RBAC) i Microsoft Entra ID, aby nawiązać połączenie bez kluczy z usługą Azure AI Search. Następnie używasz języka Python w programie Visual Studio Code do interakcji z usługą.

Połączenia bez kluczy zapewniają zwiększone zabezpieczenia dzięki szczegółowym uprawnieniam i uwierzytelnianiu opartego na tożsamościach. Nie zalecamy kodowania kluczy interfejsu API, ale jeśli wolisz je, zobacz Łączenie z usługą Azure AI Search przy użyciu kluczy.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.

• Usługa Azure AI Search w dowolnym regionie lub poziomie.

• Azure CLI do uwierzytelniania bez klucza w Microsoft Entra ID.

• Program Visual Studio Code z rozszerzeniem języka Python i pakietem Jupyter.

Konfigurowanie dostępu opartego na rolach

W tej sekcji włączysz RBAC w usłudze Azure AI Search i przypiszesz niezbędne role do tworzenia, załadowania i wykonywania zapytań dotyczących obiektów wyszukiwania. Aby uzyskać więcej informacji na temat tych kroków, zobacz Connect to Azure AI Search using roles (Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról).

Aby skonfigurować dostęp:

1. Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.

2. W okienku po lewej stronie wybierz pozycję Klucze ustawień>.

3. Wybierz Kontrola dostępu oparta na rolach (RBAC) lub Obie, jeśli potrzebujesz czasu na przeniesienie klientów do RBAC.

   

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

5. Wybierz Dodaj>Dodaj przypisanie roli.

   

6. Przypisz rolę Współautor usługi wyszukiwania do konta użytkownika lub tożsamości zarządzanej.

7. Powtórz przypisanie roli dla współautora danych indeksu wyszukiwania.

Uzyskiwanie informacji o usłudze

W tej sekcji pobierzesz identyfikator subskrypcji i punkt końcowy usługi Azure AI Search. Jeśli masz tylko jedną subskrypcję, pomiń identyfikator subskrypcji i pobierz tylko punkt końcowy. Używasz tych wartości w pozostałych sekcjach tego przewodnika Szybki Start.

Aby uzyskać informacje o usłudze:

1. Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.

2. W okienku po lewej stronie wybierz pozycję Przegląd.

3. Zanotuj identyfikator subskrypcji i punkt końcowy.

   

Zaloguj się do Azure

Przed nawiązaniem połączenia z usługą Azure AI Search użyj interfejsu wiersza polecenia platformy Azure, aby zalogować się do subskrypcji zawierającej usługę. Ten krok ustanawia tożsamość Microsoft Entra, której DefaultAzureCredential używa do uwierzytelniania żądań w następnej sekcji.

Aby się zalogować:

1. W systemie lokalnym otwórz narzędzie wiersza polecenia.

2. Zaloguj się do Azure. Jeśli masz wiele subskrypcji, wybierz tę, której identyfikator został uzyskany w obszarze Uzyskiwanie informacji o usłudze.

   az login
   

Nawiązywanie połączenia z usługą Azure AI Search

Uwaga / Notatka

W tej sekcji przedstawiono podstawowy wzorzec języka Python dla połączeń bez klucza. Aby uzyskać kompleksowe wskazówki, zapoznaj się z konkretnym przewodnikiem typu "Szybki start" lub samouczek, takim jak Szybki start: uruchamianie agentowego wyszukiwania w usłudze Azure AI Search.

Notesy języka Python w programie Visual Studio Code umożliwiają wysyłanie żądań do usługi Azure AI Search. W przypadku uwierzytelniania żądań użyj DefaultAzureCredential klasy z biblioteki tożsamości platformy Azure.

Aby nawiązać połączenie przy użyciu języka Python:

1. W systemie lokalnym otwórz program Visual Studio Code.

2. Utwórz plik .ipynb.

3. Utwórz komórkę kodu, aby zainstalować biblioteki azure-identity i azure-search-documents .

   pip install azure-identity azure-search-documents
   

4. Utwórz kolejną komórkę kodu, aby uwierzytelnić się i nawiązać połączenie z usługą wyszukiwania.

   from azure.identity import DefaultAzureCredential
   from azure.search.documents.indexes import SearchIndexClient
   
   service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
   credential = DefaultAzureCredential()
   client = SearchIndexClient(endpoint=service_endpoint, credential=credential)
   
   # List existing indexes
   indexes = client.list_indexes()
   
   for index in indexes:
      index_dict = index.as_dict()
      print(json.dumps(index_dict, indent=2))
   

5. Ustaw service_endpoint na wartość uzyskaną w Pobieranie informacji o usłudze.

6. Wybierz opcję Uruchom wszystko, aby uruchomić obie komórki kodu.

   Dane wyjściowe powinny zawierać listę istniejących indeksów (jeśli istnieją) w usłudze wyszukiwania wskazujących pomyślne połączenie.

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

Jeśli wystąpi błąd 401, wykonaj następujące kroki rozwiązywania problemów:

• Ponownie skonfiguruj dostęp oparty na rolach. Usługa wyszukiwania musi mieć włączoną kontrolę dostępu opartą na rolach lub obie . Zasady na poziomie subskrypcji lub grupy zasobów mogą również zastąpić przypisania ról.

• Ponownie zaloguj się do platformy Azure. Musisz zalogować się do subskrypcji zawierającej usługę wyszukiwania.

• Upewnij się, że zmienna punktu końcowego jest owinięta w cudzysłowy.

• Jeśli wszystko inne nie powiedzie się, uruchom ponownie urządzenie, aby usunąć buforowane tokeny, a następnie powtórz kroki opisane w tym przewodniku Szybki start, zaczynając od pozycji Zaloguj się do platformy Azure.

Przewodnik szybkiego startu: W tym przewodniku użyjesz kontroli dostępu opartej na rolach (RBAC) i Microsoft Entra ID, aby nawiązać bezkluczowe połączenie z usługą Azure AI Search. Następnie użyjesz interfejsu REST w programie Visual Studio Code do interakcji z usługą.

Połączenia bez kluczy zapewniają zwiększone zabezpieczenia dzięki szczegółowym uprawnieniam i uwierzytelnianiu opartego na tożsamościach. Nie zalecamy kodowania kluczy interfejsu API, ale jeśli wolisz je, zobacz Łączenie z usługą Azure AI Search przy użyciu kluczy.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.

• Usługa Azure AI Search w dowolnym regionie lub poziomie.

• Azure CLI do uwierzytelniania bez klucza w Microsoft Entra ID.

• Program Visual Studio Code z rozszerzeniem klienta REST.

Konfigurowanie dostępu opartego na rolach

W tej sekcji włączysz RBAC w usłudze Azure AI Search i przypiszesz niezbędne role do tworzenia, importowania i wykonywania zapytań dotyczących obiektów wyszukiwania. Aby uzyskać więcej informacji na temat tych kroków, zobacz Connect to Azure AI Search using roles (Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról).

Aby skonfigurować dostęp:

1. Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.

2. W okienku po lewej stronie wybierz pozycję Klucze ustawień>.

3. Wybierz Kontrola dostępu oparta na rolach (RBAC) lub Obie, jeśli potrzebujesz czasu na przeniesienie klientów do RBAC.

   

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

5. Wybierz Dodaj>Dodaj przypisanie roli.

   

6. Przypisz rolę Współautor usługi wyszukiwania do konta użytkownika lub tożsamości zarządzanej.

7. Powtórz przypisanie roli dla współautora danych indeksu wyszukiwania.

Uzyskiwanie informacji o usłudze

W tej sekcji pobierzesz identyfikator subskrypcji i punkt końcowy usługi Azure AI Search. Jeśli masz tylko jedną subskrypcję, pomiń identyfikator subskrypcji i pobierz tylko punkt końcowy. Używasz tych wartości w pozostałych sekcjach tego przewodnika Szybki Start.

Aby uzyskać informacje o usłudze:

1. Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.

2. W okienku po lewej stronie wybierz pozycję Przegląd.

3. Zanotuj identyfikator subskrypcji i punkt końcowy.

   

Uzyskiwanie tokenu

Przed nawiązaniem połączenia z usługą Azure AI Search użyj Azure CLI, aby zalogować się do subskrypcji zawierającej usługę i wygenerować token Microsoft Entra ID. Ten token służy do uwierzytelniania żądań w następnej sekcji.

Aby uzyskać token:

1. W systemie lokalnym otwórz narzędzie wiersza polecenia.

2. Zaloguj się do Azure. Jeśli masz wiele subskrypcji, wybierz tę, której identyfikator został uzyskany w obszarze Uzyskiwanie informacji o usłudze.

   az login
   

3. Generowanie tokenu dostępu.

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

4. Zanotuj dane wyjściowe tokenu.

Nawiązywanie połączenia z usługą Azure AI Search

Uwaga / Notatka

W tej sekcji przedstawiono podstawowy wzorzec REST dla połączeń bez kluczy. Aby uzyskać kompleksowe wskazówki, zapoznaj się z konkretnym przewodnikiem typu "Szybki start" lub samouczek, takim jak Szybki start: uruchamianie agentowego wyszukiwania w usłudze Azure AI Search.

Rozszerzenie klienta REST w programie Visual Studio Code umożliwia wysyłanie żądań do usługi Azure AI Search. W przypadku uwierzytelniania żądań dołącz Authorization nagłówek zawierający wcześniej wygenerowany token Microsoft Entra ID.

Aby nawiązać połączenie przy użyciu interfejsu REST:

1. W systemie lokalnym otwórz program Visual Studio Code.

2. Utwórz plik .rest lub .http.

3. Wklej następujące symbole zastępcze i żądanie do pliku.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
   @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
   
   ### List existing indexes
   GET {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
      Content-Type: application/json
      Authorization: Bearer {{token}}
   

4. Zastąp @baseUrl wartością uzyskaną w Uzyskiwanie informacji o usłudze.

5. Zastąp ciąg @token wartością uzyskaną w obszarze Uzyskiwanie tokenu.

6. W obszarze ### List existing indexeswybierz pozycję Wyślij żądanie.

   Powinnaś otrzymać odpowiedź HTTP/1.1 200 OK wskazującą pomyślne nawiązanie połączenia z usługą wyszukiwania.

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

Jeśli wystąpi błąd 401, wykonaj następujące kroki rozwiązywania problemów:

• Ponownie skonfiguruj dostęp oparty na rolach. Usługa wyszukiwania musi mieć włączoną kontrolę dostępu opartą na rolach lub obie . Zasady na poziomie subskrypcji lub grupy zasobów mogą również zastąpić przypisania ról.

• Ponownie odwiedź Pobierz token. Musisz zalogować się do subskrypcji zawierającej usługę wyszukiwania.

• Upewnij się, że zmienne punktu końcowego i tokenu nie mają otaczających cudzysłowów ani dodatkowych spacji.

• Upewnij się, że token nie ma symbolu @ w nagłówku żądania. Jeśli na przykład zmienna to @token, odwołanie w żądaniu powinno mieć wartość {{token}}.

• Jeśli wszystko inne nie powiedzie się, uruchom ponownie urządzenie, aby usunąć buforowane tokeny, a następnie powtórz kroki opisane w tym przewodniku Szybki start, zaczynając od pozycji Pobierz token.

Treści powiązane

• Konfigurowanie tożsamości zarządzanej w usłudze Azure AI Search
• Łączenie aplikacji z usługą Azure AI Search przy użyciu tożsamości
• Konfigurowanie reguł dostępu do sieci i zapory dla usługi Azure AI Search