Udostępnij przez

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

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.

    Zrzut ekranu przedstawiający opcje kontroli dostępu w witrynie Azure Portal.

  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.

    Zrzut ekranu przedstawiający menu rozwijane służące do dodawania przypisania roli w witrynie Azure Portal.

  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.

    Zrzut ekranu przedstawiający identyfikator subskrypcji i punkt końcowy w witrynie Azure Portal.

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. Sprawdź aktywną subskrypcję i dzierżawę w środowisku lokalnym.

    az account show

  3. Jeśli aktywna subskrypcja i konto w dzierżawie nie są prawidłowe dla usługi wyszukiwania, uruchom następujące polecenia, aby zaktualizować ich wartości. Identyfikator subskrypcji można znaleźć na stronie Przegląd usługi wyszukiwania w witrynie Azure Portal. Aby znaleźć identyfikator dzierżawcy, wybierz nazwę subskrypcji na stronie Przegląd, a następnie znajdź wartość Grupa zarządzania nadrzędna.

     az account set --subscription <your-subscription-id>

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

Uwaga / Notatka

W tej sekcji przedstawiono podstawowy wzorzec języka Python dla połączeń bez klucza. Aby uzyskać kompleksowe wskazówki, zobacz konkretny przewodnik Szybki start lub samouczek, taki jak Szybki start: używanie pobierania agentów 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ą 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.

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ż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

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.

    Zrzut ekranu przedstawiający opcje kontroli dostępu w witrynie Azure Portal.

  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.

    Zrzut ekranu przedstawiający menu rozwijane służące do dodawania przypisania roli w witrynie Azure Portal.

  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.

    Zrzut ekranu przedstawiający identyfikator subskrypcji i punkt końcowy w witrynie Azure Portal.

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ę.

Aby się zalogować:

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

  2. Sprawdź aktywną subskrypcję i dzierżawę w środowisku lokalnym.

    az account show

  3. Jeśli aktywna subskrypcja i dzierżawa nie są prawidłowe dla usługi wyszukiwania, uruchom następujące polecenia, aby zaktualizować ich wartości. Identyfikator subskrypcji można znaleźć na stronie Przegląd usługi wyszukiwania w witrynie Azure Portal. Aby znaleźć identyfikator klienta, wybierz nazwę swojej subskrypcji na stronie Przegląd, a następnie znajdź wartość Nadrzędnej grupy zarządzania.

     az account set --subscription <your-subscription-id>

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

Uzyskiwanie tokenu

Wywołania interfejsu API REST wymagają dołączenia tokenu Microsoft Entra ID. Ten token służy do uwierzytelniania żądań w następnej sekcji.

Aby uzyskać token:

  1. Za pomocą tego samego narzędzia wiersza polecenia wygeneruj token dostępu.

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

  2. Zanotuj dane wyjściowe tokenu.

Uwaga / Notatka

W tej sekcji przedstawiono podstawowy wzorzec REST dla połączeń bez kluczy. Aby uzyskać kompleksowe wskazówki, zobacz konkretny przewodnik Szybki start lub samouczek, taki jak Szybki start: używanie pobierania agentów 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 zmienne 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=2025-09-01  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  4. Ustaw @baseUrl na wartość uzyskaną w Pobieranie informacji o usłudze.

  5. Ustaw @token do wartości, którą uzyskałeś w 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ą unieważnić przypisania ról.

  • Ponownie zaloguj się do platformy Azure. 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 Zaloguj się do platformy Azure.

Treści powiązane

  • Last updated on