使用金鑰連接 Foundry IQ(Azure AI 搜尋服務)

附註

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

Foundry IQ(Azure AI 搜尋服務)支援基於身份與金鑰的驗證(預設)以連接您的 Foundry IQ 服務。

若對 Foundry IQ 服務端點的請求與 API 金鑰皆有效,且 Foundry IQ 服務已設定允許在請求上使用 API 金鑰,該請求即被接受。

重要事項

當您建立 Foundry IQ 服務時,預設採用金鑰驗證,但這並非最安全的選項。 我們建議您將其取代為角色型存取。

先決條件

您必須是擁有者、貢獻者或 搜尋服務貢獻 者才能查看或管理鑰匙。

預設為啟用

在Azure入口網站中,認證是在 Settings>Keys頁面指定。 選項設為 API 金鑰 (預設) 或兩者,允許在要求上使用 API 金鑰。

Azure 入口網站中金鑰頁面的螢幕截圖。

金鑰的類型

API 金鑰是由 52 個隨機產生的數字和字母所組成的唯一字串。 管理金鑰或查詢金鑰在外觀上並無差別。 如果你忘記應用程式中指定了哪種金鑰,可以在Azure入口網站 檢查金鑰值。

有兩種金鑰可用來驗證要求:

類型 權限等級 它是如何被創造的 最大值
管理 所有資料平面 (內容) 作業的完整存取權 (讀寫)。 服務建立時會產生兩個管理密鑰,主密鑰與次要密鑰,並可按需分別重新生成。 具備兩個可讓您在使用第二個金鑰持續存取服務的同時,將其中一個金鑰輪替更新。 2
查詢 唯讀存取權,範圍設定為搜尋索引的文件集合 服務會產生一個查詢金鑰。 Foundry IQ 服務管理員可按需建立更多。 50

尋找現有的金鑰

你可以使用 Azure portal、PowerShell、Azure CLI 或 REST API 來查看和管理 API 金鑰。

  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 從左側窗格選擇 設定>鍵 以查看管理員鍵與查詢鍵。

    顯示 API 金鑰的入口網站頁面截圖。

在連接中使用金鑰

基於金鑰的認證僅用於資料平面(內容)請求,例如建立或查詢索引,以及使用 搜尋服務 REST API 執行的其他操作。

在你的原始碼中,你可以直接在請求標頭指定 API 金鑰。 或者,你也可以把它當作 環境變數 或應用程式設定存在專案裡,然後在請求中引用該變數。

  • 系統管理金鑰可用來建立、修改或刪除物件。
  • 管理金鑰也用於 GET 物件定義和系統資訊,例如 LIST 索引 或 GET 服務統計資料。
  • 查詢金鑰通常會散發給發出查詢的用戶端應用程式。

回想一下,金鑰驗證預設為啟用,並支援索引和查詢等資料平面作業。

不過,如果您停用 API 金鑰,並設定角色指派,Azure 入口網站就會改用角色指派。

建立查詢金鑰

查詢金鑰針對以文件集合為目標的作業,用於唯讀存取索引內的文件。 搜尋、篩選和建議查詢全都是採用查詢金鑰的作業。 任何傳回系統資料或物件定義的唯讀作業 (例如索引定義或索引子狀態) 都需要系統管理金鑰。

限制用戶端應用程式中的存取和作業是保護服務上搜尋資產的必要條件。 請一律針對源自用戶端應用程式的任何查詢使用查詢金鑰,而非使用系統管理員金鑰。

  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 從左側窗格選擇 設定>金鑰 以查看 API 金鑰。

  3. 在 [管理查詢金鑰] 下,使用已為您服務產生的查詢金鑰,或建立新的查詢金鑰。 預設查詢金鑰並未命名,但可命名其他產生的查詢金鑰以方便管理。

    查詢金鑰管理選項的螢幕截圖。

重新產生系統管理金鑰

針對每個服務,會建立兩個系統管理金鑰,讓您可以輪換主要金鑰,同時使用次要金鑰以獲得業務持續性。

  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 從左窗格中,選取 [設定]>[金鑰]。

  3. 複製副鑰匙。

  4. 針對所有的應用程式,更新 API 金鑰設定以使用次要金鑰。

  5. 重新產生主要金鑰。

  6. 更新所有應用程式以使用新的主要金鑰。

如果您不小心同時重新產生這兩個金鑰,則使用這些金鑰的所有用戶端要求都會失敗,並發生 HTTP 403 禁止。 不過,並不會刪除內容,且不會將您永久鎖定。

你仍然可以透過 Azure 入口網站或程式化方式存取這項服務。 管理功能是透過訂用帳戶識別碼而非服務 API 金鑰運作,因此即使您的 API 金鑰無法使用,管理功能仍可使用。

透過入口網站或管理層建立新的金鑰之後,一旦您依要求提供這些金鑰,存取權就會還原至您的內容 (索引、索引子、資料來源、同義字對應)。

從金鑰遷移到角色

若要將基於金鑰的存取轉換為基於角色的存取,請使用以下角色指派:

  • 若要取代管理員金鑰,請指派 搜尋服務貢獻 者管理搜尋物件,並指定搜尋 索引資料貢獻 者以直接存取資料平面。

  • 若要替換查詢鍵,請指派 搜尋索引資料閱讀器。

重要事項

Search Service Contributor 是一個控制平面角色,可以取得管理員金鑰,提供對資料平面的完整讀寫存取權限。 只把這個角色授予值得信賴的使用者。

安全金鑰

使用角色指派來限制對 API 金鑰的存取。

您無法使用客戶自控金鑰加密來加密 API 金鑰。 只有 Foundry IQ 服務本身內的敏感資料(例如資料來源物件定義中的索引內容或連線字串)才能進行 CMK 加密。

  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 從左側窗格選擇 存取控制(IAM),然後選擇 角色指派 標籤。

  3. 在 [角色] 篩選條件中,選取有權檢視或管理金鑰的角色 (擁有者、參與者、搜尋服務參與者)。 指派給這些角色的產生安全主體對您的 Foundry IQ 服務具有關鍵權限。

  4. 作為預防措施,也請檢查 [傳統管理員] 索引標籤,以判斷管理員和共同管理員是否具有存取權。

最佳作法

  • 若為生產工作負載,請改用 Microsoft Entra ID 和角色型存取。 或者,如果你想繼續使用 API 金鑰,務必監控 誰能存取你的 API 金鑰 ,並定期 重新產生 API 金鑰 。

  • 如果資料洩漏不具風險 (例如,使用範例資料時),且您在防火牆後方作業,請只使用 API 金鑰。 公開 API 金鑰會讓您的資料與 Foundry IQ 服務面臨未經授權使用的風險。

  • 如果你使用 API 金鑰,請將它安全地存放在其他地方,例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰,且切勿公開張貼金鑰。

  • 在發佈程式碼、範例和訓練教材前,請務必檢查您的程式碼,以確定您不會不小心公開 API 金鑰。