Rychlý start: Připojení k vyhledávací službě

Poznámka:

Azure AI Vyhledávač je k dispozici prostřednictvím portálu Azure, rozhraní REST API a Sady Azure SDK. Podporuje také Foundry IQ, spravovanou znalostní vrstvu, která transformuje podnikový obsah na opakovaně použitelné znalostní báze s podporou oprávnění pro agenty na portálu Microsoft Foundry.

V tomto rychlém startu použijete řízení přístupu na základě role (RBAC) a ID Microsoft Entra k navázání bezklíčového připojení ke službě Azure AI Vyhledávač. Pak použijete Python v editoru Visual Studio Code k interakci s vaší službou.

Bezklíčová připojení poskytují lepší zabezpečení prostřednictvím podrobných oprávnění a ověřování na základě identit. Nedoporučujeme pevně zakódované klíče rozhraní API, ale pokud jim dáváte přednost, přečtěte si téma Připojení k Azure AI Vyhledávač pomocí klíčů.

Požadavky

Konfigurace přístupu na základě role

V této části povolíte RBAC ve službě Azure AI Vyhledávač a přiřadíte potřebné role pro vytváření, načítání a dotazování vyhledávacích objektů. Další informace o těchto krocích najdete v tématu Připojení k Azure AI Vyhledávač pomocí rolí.

Konfigurace přístupu:

  1. Na webu Azure Portal přejděte do vyhledávací služby.

  2. V levém podokně vyberte Klíče nastavení>.

  3. Pokud potřebujete čas na převod klientů na RBAC, vyberte řízení přístupu na základě role nebo obojí .

    Snímek obrazovky s možnostmi řízení přístupu na webu Azure Portal

  4. V levém podokně vyberte Řízení přístupu (IAM).

  5. Vyberte Přidat>Přiřadit roli.

    Snímek obrazovky s rozevírací nabídkou pro přidání přiřazení role na webu Azure Portal

  6. Přiřaďte roli Přispěvatel vyhledávací služby k vašemu uživatelskému účtu nebo spravované identitě.

  7. Opakujte přiřazení role pro Přispěvatel dat indexu vyhledávání.

Získání informací o službě

V této části načtete ID předplatného a koncový bod služby Azure AI Vyhledávač. Pokud máte jenom jedno předplatné, přeskočte ID předplatného a načtěte pouze koncový bod. Tyto hodnoty použijete ve zbývajících částech tohoto rychlého startu.

Získání informací o službě:

  1. Na webu Azure Portal přejděte do vyhledávací služby.

  2. V levém podokně vyberte Přehled.

  3. Poznamenejte si ID předplatného a koncový bod.

    Snímek obrazovky s ID předplatného a koncovým bodem na webu Azure Portal

Přihlásit se do Azure

Než se připojíte ke službě Azure AI Vyhledávač, přihlaste se pomocí Azure CLI k předplatnému, které obsahuje vaši službu. Tento krok vytvoří vaši identitu Microsoft Entra, která DefaultAzureCredential používá k ověřování požadavků v další části.

Přihlášení:

  1. V místním systému otevřete nástroj příkazového řádku.

  2. Zkontrolujte aktivní předplatné a tenanta ve vašem místním prostředí.

    az account show

  3. Pokud aktivní předplatné a tenant nejsou pro vaši vyhledávací službu platné, aktualizujte jejich hodnoty spuštěním následujících příkazů. ID předplatného najdete na stránce Přehled vyhledávací služby na webu Azure Portal. Pokud chcete najít ID klienta, vyberte název svého předplatného na stránce Přehled a poté vyhledejte hodnotu nadřazené skupiny pro správu.

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

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

Poznámka:

Tato část znázorňuje základní vzor Pythonu pro připojení bez klíčů. Podrobné pokyny najdete v konkrétním rychlém startu nebo kurzu, jako je Quickstart: Agentické načítání.

Poznámkové bloky Pythonu v editoru Visual Studio Code můžete použít k odesílání požadavků do služby Azure AI Vyhledávač. K ověření požadavku použijte DefaultAzureCredential třídu z knihovny Azure Identity.

Připojení pomocí Pythonu:

  1. V místním systému otevřete Visual Studio Code.

  2. Vytvořte soubor .ipynb.

  3. Vytvořte buňku kódu pro instalaci azure-identity a azure-search-documents knihovny.

    pip install azure-identity azure-search-documents

  4. Vytvořte další buňku kódu pro ověření a připojení k vyhledávací službě.

    import json
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. Nastavte service_endpoint hodnotu, kterou jste získali v získání informací o službě.

  6. Vyberte Spustit vše pro spuštění obou buněk kódu.

    Výstup by měl obsahovat seznam existujících indexů (pokud existuje) ve vyhledávací službě, což značí úspěšné připojení.

Řešení chyb 401

Pokud dojde k chybě 401, postupujte podle těchto kroků pro řešení potíží:

  • Znovu se můžete vrátit k konfiguraci přístupu na základě role. Vaše vyhledávací služba musí mít povolené řízení přístupu na základě role nebo obojí . Zásady na úrovni předplatného nebo skupiny prostředků mohou mít přednost před vašimi přiřazeními rolí.

  • Znovu se přihlaste k Azure. Musíte se přihlásit k předplatnému, které obsahuje vaši vyhledávací službu.

  • Ujistěte se, že proměnná koncového bodu obsahuje okolní uvozovky.

  • Pokud všechno ostatní selže, restartujte zařízení, aby se odebraly tokeny uložené v mezipaměti, a pak zopakujte kroky v tomto rychlém startu počínaje přihlášením do Azure.

V tomto rychlém startu použijete řízení přístupu na základě role (RBAC) a ID Microsoft Entra k navázání bezklíčového připojení ke službě Azure AI Vyhledávač. K interakci se službou pak použijete REST v editoru Visual Studio Code.

Bezklíčová připojení poskytují lepší zabezpečení prostřednictvím podrobných oprávnění a ověřování na základě identit. Nedoporučujeme pevně zakódované klíče rozhraní API, ale pokud jim dáváte přednost, přečtěte si téma Připojení k Azure AI Vyhledávač pomocí klíčů.

Požadavky

Konfigurace přístupu na základě role

V této části povolíte RBAC ve službě Azure AI Vyhledávač a přiřadíte potřebné role pro vytváření, načítání a dotazování vyhledávacích objektů. Další informace o těchto krocích najdete v tématu Připojení k Azure AI Vyhledávač pomocí rolí.

Konfigurace přístupu:

  1. Na webu Azure Portal přejděte do vyhledávací služby.

  2. V levém podokně vyberte Klíče nastavení>.

  3. Pokud potřebujete čas na převod klientů na RBAC, vyberte řízení přístupu na základě role nebo obojí .

    Snímek obrazovky s možnostmi řízení přístupu na webu Azure Portal

  4. V levém podokně vyberte Řízení přístupu (IAM).

  5. Vyberte Přidat>Přiřadit roli.

    Snímek obrazovky s rozevírací nabídkou pro přidání přiřazení role na webu Azure Portal

  6. Přiřaďte roli Přispěvatel vyhledávací služby k vašemu uživatelskému účtu nebo spravované identitě.

  7. Opakujte přiřazení role pro Přispěvatel dat indexu vyhledávání.

Získání informací o službě

V této části načtete ID předplatného a koncový bod služby Azure AI Vyhledávač. Pokud máte jenom jedno předplatné, přeskočte ID předplatného a načtěte pouze koncový bod. Tyto hodnoty použijete ve zbývajících částech tohoto rychlého startu.

Získání informací o službě:

  1. Na webu Azure Portal přejděte do vyhledávací služby.

  2. V levém podokně vyberte Přehled.

  3. Poznamenejte si ID předplatného a koncový bod.

    Snímek obrazovky s ID předplatného a koncovým bodem na webu Azure Portal

Přihlásit se do Azure

Než se připojíte ke službě Azure AI Vyhledávač, přihlaste se pomocí Azure CLI k předplatnému, které obsahuje vaši službu.

Přihlášení:

  1. V místním systému otevřete nástroj příkazového řádku.

  2. Zkontrolujte aktivní předplatné a tenanta ve vašem místním prostředí.

    az account show

  3. Pokud aktivní předplatné a tenant nejsou pro vaši vyhledávací službu platné, aktualizujte jejich hodnoty spuštěním následujících příkazů. ID předplatného najdete na stránce Přehled vyhledávací služby na webu Azure Portal. Pokud chcete najít ID klienta, vyberte název svého předplatného na stránce Přehled a poté vyhledejte hodnotu nadřazené skupiny pro správu.

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

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

Získání tokenu

Volání rozhraní REST API vyžadují zahrnutí tokenu MICROSOFT Entra ID. Tento token použijete k ověření požadavků v další části.

Získání tokenu:

  1. Pomocí stejného nástroje příkazového řádku vygenerujte přístupový token.

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

  2. Poznamenejte si výstup tokenu.

Poznámka:

Tato část znázorňuje základní vzor REST pro připojení bez klíčů. Podrobné pokyny najdete v konkrétním rychlém startu nebo kurzu, jako je Quickstart: Agentické načítání.

Rozšíření REST Client v editoru Visual Studio Code můžete použít k odesílání požadavků do služby Azure AI Vyhledávač. Pro ověření požadavku zahrňte hlavičku Authorization s tokenem ID Microsoft Entra, který jste předtím vygenerovali.

Připojení pomocí REST:

  1. V místním systému otevřete Visual Studio Code.

  2. Vytvořte .rest soubor nebo .http soubor.

  3. Do souboru vložte následující proměnné a požadavek.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

### List existing indexes
GET {{baseUrl}}/indexes?api-version=2026-04-01  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  4. Nastavte @baseUrl hodnotu, kterou jste získali v získání informací o službě.

  5. Nastavte @token hodnotu, kterou jste získali v tokenu Get.

  6. V části ### List existing indexesVyberte Možnost Odeslat žádost.

    Měla by se zobrazit HTTP/1.1 200 OK odpověď označující úspěšné připojení k vyhledávací službě.

Řešení chyb 401

Pokud dojde k chybě 401, postupujte podle těchto kroků pro řešení potíží:

  • Znovu se můžete vrátit k konfiguraci přístupu na základě role. Vaše vyhledávací služba musí mít povolené řízení přístupu na základě role nebo obojí . Zásady na úrovni předplatného nebo skupiny prostředků mohou mít přednost před vašimi přiřazeními rolí.

  • Znovu se přihlaste k Azure. Musíte se přihlásit k předplatnému, které obsahuje vaši vyhledávací službu.

  • Ujistěte se, že proměnné koncového bodu a tokenu neobsahují okolní uvozovky ani nadbytečné mezery.

  • Ujistěte se, že token v hlavičce požadavku neobsahuje @ symbol. Pokud je proměnná například @token, odkaz v požadavku by měl být {{token}}.

  • Pokud všechno ostatní selže, restartujte zařízení, aby se odebraly tokeny uložené v mezipaměti, a pak zopakujte kroky v tomto rychlém startu počínaje přihlášením do Azure.

Související obsah

  • Last updated on