備註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
在此快速入門中,您將使用角色型存取控制 (RBAC) 和 Microsoft Entra ID,與您的 Foundry IQ (Azure AI 搜尋服務) 服務建立免金鑰連線。 接著,您會在 Visual Studio Code 中使用 Python 與服務互動。
無密鑰連線可透過細微的許可權和身分識別型驗證來提供增強的安全性。 我們不建議使用硬編碼的 API 金鑰,但如果您偏好,請參閱「 使用金鑰連接至 Foundry IQ」。
先決條件
具有有效訂閱的 Azure 帳戶。 免費建立帳戶。
Foundry IQ 服務,適用於任何地區或層級。
Azure CLI 用於與 Microsoft Entra ID 進行無密鑰驗證。
設定角色型存取
在本節中,您為您的 Foundry IQ(Azure AI 搜尋服務)服務啟用 RBAC,並指派建立、載入及查詢搜尋物件所需的角色。 有關這些步驟的更多資訊,請參閱「使用角色連接至 Foundry IQ」。
若要設定存取:
前往 Azure 入口網站中的 Foundry IQ 服務。
從左窗格中,選取 [ 設定 > 金鑰]。
如果您需要時間將客戶端轉換為 RBAC,請選取 [角色型存取控制 ] 或 [ 兩者 ]。
從左窗格中,選取 [訪問控制][IAM]。
選取 新增>新增角色指派。
將 搜尋服務參與者 角色指派給用戶帳戶或受控識別。
重複 搜尋索引數據參與者的角色指派。
取得服務資訊
在此節中,您將取得 Foundry IQ 服務的訂閱 ID 與端點。 如果您只有一個訂用帳戶,請略過訂用帳戶標識碼,並只擷取端點。 在本快速入門的其餘區段中,您會使用這些值。
若要取得您的服務資訊:
前往 Azure 入口網站中的 Foundry IQ 服務。
從左窗格中,選取 [ 概觀]。
記下訂用帳戶標識碼和端點。
登入 Azure
在連接到您的 Foundry IQ 服務之前,請使用 Azure CLI 登入包含您服務的訂用帳戶。 此步驟會建立您的Microsoft Entra 身分識別,該 DefaultAzureCredential 身分識別會在下一節中用來驗證要求。
若要登入:
在您的本機系統上,開啟命令行工具。
請檢查本機環境中的作用中訂用帳戶和租用戶。
az account show如果目前的訂閱與租戶對您的 Foundry IQ 服務無效,請執行下列指令以更新其值。 您可以在 Azure 入口網站的 Foundry IQ 服務概覽頁面找到訂閱 ID。 要找到租戶 ID,請在 「概覽 」頁面選擇您的訂閱名稱,然後找到 父管理群組 的值。
az account set --subscription <your-subscription-id> az login --tenant <your-tenant-id>
連結至 Foundry IQ
備註
本節說明無密鑰連線的基本 Python 模式。 如需完整指引,請參閱特定的快速入門或教學,例如快速 入門:代理檢索。
你可以在 Visual Studio Code 中使用 Python 筆記本向 Foundry IQ 服務發送請求。 針對要求驗證,請使用 DefaultAzureCredential Azure 身分識別程式庫中的類別。
若要使用 Python 進行連線:
在您的本機系統上,開啟 Visual Studio Code。
建立
.ipynb檔案。建立程式碼單元以安裝
azure-identity和azure-search-documents庫。pip install azure-identity azure-search-documents建立另一個程式碼儲存格,以進行驗證並連線到您的 Foundry IQ 服務。
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))將
service_endpoint設定為從 取得服務資訊 所得的值。選擇 全部執行 來執行兩個程式碼區塊。
輸出應列出您的 Foundry IQ 服務上現有的索引(如有),表示已成功連線。
針對 401 錯誤進行疑難排解
如果您遇到 401 錯誤,請遵循下列疑難解答步驟:
重新檢視 配置基於角色的存取權限。 您的 Foundry IQ 服務必須啟用 基於角色的存取控制 或 兩者皆 啟用。 訂閱或資源群組層級的政策可能會取代你的角色分配。
重新查看登入 Azure。 您必須登入包含 Foundry IQ 服務的訂閱。
請確定您的端點變數有周圍的引號。
如果所有其他動作都失敗,請重新啟動您的裝置以移除快取的權杖,然後重複此快速入門中的步驟,從 [登入 Azure] 開始。
在此快速入門中,您將使用基於角色的存取控制(RBAC)與 Microsoft Entra ID,建立無金鑰連接您的 Foundry IQ(Azure AI 搜尋服務)服務。 然後在 Visual Studio Code 中使用 REST 來與您的服務互動。
無密鑰連線可透過細微的許可權和身分識別型驗證來提供增強的安全性。 我們不建議使用硬編碼的 API 金鑰,但如果您偏好,請參閱「 使用金鑰連接至 Foundry IQ」。
先決條件
具有有效訂閱的 Azure 帳戶。 免費建立帳戶。
Foundry IQ 服務,適用於任何地區或層級。
Azure CLI 用於與 Microsoft Entra ID 進行無密鑰驗證。
設定角色型存取
在本節中,您為您的 Foundry IQ(Azure AI 搜尋服務)服務啟用 RBAC,並指派建立、載入及查詢搜尋物件所需的角色。 有關這些步驟的更多資訊,請參閱 「使用角色連線至 Foundry IQ」。
若要設定存取:
前往 Azure 入口網站中的 Foundry IQ 服務。
從左窗格中,選取 [ 設定 > 金鑰]。
如果您需要時間將客戶端轉換為 RBAC,請選取 [角色型存取控制 ] 或 [ 兩者 ]。
從左窗格中,選取 [訪問控制][IAM]。
選取 新增>新增角色指派。
將 搜尋服務參與者 角色指派給用戶帳戶或受控識別。
重複 搜尋索引數據參與者的角色指派。
取得服務資訊
在此節中,您將取得 Foundry IQ 服務的訂閱 ID 與端點。 如果您只有一個訂用帳戶,請略過訂用帳戶標識碼,並只擷取端點。 在本快速入門的其餘區段中,您會使用這些值。
若要取得您的服務資訊:
前往 Azure 入口網站中的 Foundry IQ 服務。
從左窗格中,選取 [ 概觀]。
記下訂用帳戶標識碼和端點。
登入 Azure
在連接您的 Foundry IQ 服務之前,請使用 Azure CLI 登入包含您服務的訂閱。
若要登入:
在您的本機系統上,開啟命令行工具。
請檢查本機環境中的作用中訂用帳戶和租用戶。
az account show如果目前使用中的訂閱與租戶不是您的 Foundry IQ 服務所使用的有效值,請執行下列命令以更新這些值。 您可以在 Azure 入口網站的 Foundry IQ 服務概覽頁面找到訂閱 ID。 要找到租戶 ID,請在 「概覽 」頁面選擇您的訂閱名稱,然後找到 父管理群組 的值。
az account set --subscription <your-subscription-id> az login --tenant <your-tenant-id>
取得權杖
REST API 呼叫需要包含 Microsoft Entra ID 權杖。 您會使用此 token 來驗證下一節中的要求。
若要取得您的令牌:
使用相同的命令列工具,產生存取權杖。
az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv記下權杖輸出。
連結至 Foundry IQ
備註
本節說明無密鑰連線的基本 REST 模式。 如需完整指引,請參閱特定的快速入門或教學,例如快速 入門:代理檢索。
您可以使用 Visual Studio Code 中的 REST 用戶端擴充功能向您的 Foundry IQ 服務發送請求。 為了進行請求認證,請加入 Authorization 標頭,該標頭包含了您之前生成的 Microsoft Entra ID 令牌。
若要使用 REST 進行連線:
在您的本機系統上,開啟 Visual Studio Code。
建立
.rest或.http檔案。將以下變數和請求貼上到檔案中。
@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE ### List existing indexes GET {{baseUrl}}/indexes?api-version=2026-10-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}}將
@baseUrl設定為從 取得服務資訊 所得的值。設定
@token為你在 Get 代幣中獲得的數值。在 底下
### List existing indexes,選取 [ 傳送要求]。您應該會收到
HTTP/1.1 200 OK回覆,表示已成功連接您的 Foundry IQ 服務。
針對 401 錯誤進行疑難排解
如果您遇到 401 錯誤,請遵循下列疑難解答步驟:
重新檢視 配置基於角色的存取權限。 您的 Foundry IQ 服務必須啟用 基於角色的存取控制 或 兩者皆 啟用。 訂閱或資源群組層級的政策可能會取代你的角色分配。
重新查看登入 Azure。 您必須登入包含 Foundry IQ 服務的訂閱。
請確定您的端點和令牌變數沒有周圍引號或額外空格。
請確定您的權杖在要求標頭中沒有
@符號。 例如,如果變數是@token,則要求中的參考應該是{{token}}。如果所有其他動作都失敗,請重新啟動您的裝置以移除快取的權杖,然後重複此快速入門中的步驟,從 [登入 Azure] 開始。