共用方式為

使用金鑰驗證連線到 Azure AI 搜尋服務

  • 發行項

Azure AI 搜尋服務提供金鑰型驗證，可用於連線到搜尋服務。 API 金鑰是由 52 個隨機產生的數字和字母所組成的唯一字串。 如果要求和 API 金鑰都有效，則會接受對搜尋服務端點提出的要求。

預設值為金鑰型驗證。 如果您選擇角色型驗證，則可以停用它。

注意

重要術語的快速注意事項。 API 金鑰是用於驗證的 GUID。 檔索引鍵是索引內容中唯一的字串，可唯一識別搜尋索引中的檔。

API 金鑰的類型

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

類型 權限層級 最大值 建立方式
管理 所有內容作業的完整存取權 (讀寫) 2 1 當服務建立時，在入口網站中會產生兩個系統管理金鑰 (稱為「主要」和「次要」金鑰)，而且您可以視需要個別重新產生這些金鑰。
查詢 唯讀存取權，範圍設定為搜尋索引的文件集合 50 服務會產生一個查詢金鑰。 搜尋服務管理員可以視需要建立更多金鑰。

1 擁有兩個金鑰可讓您在變換一個金鑰時，使用第二個金鑰來繼續存取服務。

管理金鑰或查詢金鑰在外觀上並無差別。 兩種金鑰都是由 52 個隨機產生的英數字元所組成。 如果您忘記在應用程式中指定的是哪種類型的金鑰，您可以在入口網站中查看金鑰值。

在連線上使用 API 金鑰

API 金鑰用於數據平面（內容）要求，例如建立或存取索引，或搜尋 REST API 中代表的任何其他要求。 建立服務時，API 金鑰是資料平面作業的唯一驗證機制，但如果無法在程式碼中使用硬式編碼金鑰，則可以使用 Azure 角色取代或補充金鑰驗證。

系統管理金鑰可用來建立、修改或刪除物件。 系統管理金鑰也用於 GET 物件定義和系統資訊。

查詢金鑰通常會散發給發出查詢的用戶端應用程式。

REST 呼叫中如何使用 API 金鑰：

在要求標頭中設定系統管理金鑰。 您無法在 URI 或要求主體中傳遞系統管理金鑰。 系統管理金鑰用於建立-讀取-更新-刪除作業，以及針對向搜尋服務本身發出的要求，例如 LIST 索引 或 GET 服務統計數據。

以下是在建立索引要求上使用系統管理 API 金鑰的範例：

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

在 POST 的要求標頭中，或在 GET 的 URI 上設定查詢密鑰。 查詢索引鍵用於以集合為目標的 index/docs 作業： 搜尋檔、 自動完成、 建議或 GET 檔。

以下是搜尋檔案 （GET） 要求查詢 API 金鑰使用方式的範例：

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2023-11-01&api-key={{queryApiKey}}

注意

在要求 URI 中傳遞敏感性資料 (例如 api-key) 被視為不佳的安全性做法。 因此，Azure AI 搜尋服務只會接受查詢金鑰作為查詢字串中的 api-key。 一般規則是建議將 api-key 當作要求標頭來傳遞。

檢視或管理 API 金鑰的權限

檢視和管理 API 金鑰的權限會透過角色指派來傳達。 下列角色的成員可以檢視和重新產生金鑰：

下列角色無法存取 API 金鑰：

  • 讀取者
  • 搜尋索引資料參與者
  • 搜尋索引資料讀取者

尋找現有的金鑰

您可以在 Azure 入口網站或透過 PowerShell、Azure CLI 或 REST API 檢視及管理 API 金鑰。

  1. 登入 Azure 入口網站，然後尋找您的搜尋服務。

  2. 在 [設定] 下，選取 [金鑰] 以檢視管理員和查詢金鑰。

顯示 API 金鑰的入口網站頁面螢幕快照。

建立查詢金鑰

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

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

  1. 登入 Azure 入口網站，然後尋找您的搜尋服務。

  2. 在 [設定] 下，選取 [金鑰] 以檢視 API 金鑰。

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

    查詢金鑰管理選項的螢幕快照。

重新產生系統管理金鑰

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

  1. 在 [設定] 下，選取 [金鑰]，然後複製次要金鑰。

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

  3. 重新產生主要金鑰。

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

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

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

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

保護 API 金鑰

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

您無法使用 客戶管理的金鑰加密來加密 API 金鑰。 只有搜尋服務本身內的敏感性資料 (例如，資料來源物件定義中的索引內容或連接字串) 可以進行 CMK 加密。

  1. 在 Azure 入口網站中瀏覽至您的搜尋服務頁面。

  2. 在左側瀏覽窗格選取 [存取控制 (IAM)]，然後選取 [角色指派] 索引標籤。

  3. 在 [角色] 篩選條件中，選取有權檢視或管理金鑰的角色 (擁有者、參與者、搜尋服務參與者)。 指派給這些角色的最終安全性主體具有搜尋服務的主要權限。

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

最佳作法

  • 只有在數據洩漏不具風險時，才使用 API 金鑰（例如，使用範例數據時），以及在防火牆後方操作時。 公開 API 金鑰會對資料和未經授權使用您的搜尋服務造成風險。

  • 在發佈之前，請務必先檢查程式代碼、範例和訓練數據，以確保您未留下有效的 API 金鑰。

  • 針對生產工作負載，切換至 Microsoft Entra 標識碼和角色型存取。 或者，如果您想要繼續使用 API 金鑰，請務必一律監視有權存取您 API 金鑰的人員，並定期重新產生 API 金鑰。

另請參閱