使用金鑰驗證 連線 至 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}}
注意
傳遞敏感數據，例如 api-key 在要求 URI 中傳遞敏感數據時，會被視為不良的安全性做法。 基於這個理由，Azure AI 搜尋只會接受查詢金鑰做為 api-key 查詢字串中的 。 一般情況下，建議您將 您 api-key 當作要求標頭傳遞。
檢視或管理 API 金鑰的許可權
檢視和管理 API 金鑰的許可權會透過 角色指派來傳達。 下列角色的成員可以檢視和重新產生金鑰：
- 擁有者
- 參與者
- 搜尋服務參與者
- 管理員 istrator 和共同管理員 （傳統）
下列角色無法存取 API 金鑰：
- 讀取者
- 搜尋索引數據參與者
- 搜尋索引數據讀取器
尋找現有的金鑰
您可以在 Azure 入口網站 中，或透過PowerShell、Azure CLI或REST API來檢視和管理 API 金鑰。
登入 Azure 入口網站，然後尋找您的搜尋服務。
在 [設定] 下，選取 [金鑰] 以檢視系統管理員和查詢密鑰。
建立查詢金鑰
查詢索引鍵用於對索引內檔進行以檔集合為目標之作業的唯讀存取。 搜尋、篩選和建議查詢是採用查詢索引鍵的所有作業。 任何傳回系統數據或物件定義的只讀作業，例如索引定義或索引器狀態，都需要管理密鑰。
限制用戶端應用程式中的存取權和作業，對於保護服務上的搜尋資產至關重要。 請一律針對源自用戶端應用程式的任何查詢使用查詢金鑰，而不是系統管理密鑰。
登入 Azure 入口網站，然後尋找您的搜尋服務。
在 [設定] 下，選取 [金鑰] 以檢視 API 金鑰。
在 [管理查詢金鑰] 底下，使用已為您的服務產生的查詢密鑰，或建立新的查詢金鑰。 默認查詢索引鍵未命名，但其他產生的查詢索引鍵可以命名為可管理性。
重新產生系統管理金鑰
系統會為每個服務建立兩個系統管理密鑰，讓您可以在使用次要密鑰進行商務持續性時輪替主鍵。
在 [設定] 下，選取 [金鑰]，然後複製次要密鑰。
針對所有應用程式，更新 API 金鑰設定以使用次要金鑰。
重新產生主鍵。
更新所有應用程式以使用新的主鍵。
如果您不小心同時重新產生這兩個密鑰，使用這些金鑰的所有用戶端要求都會失敗，併發生 HTTP 403 禁止。 不過，不會刪除內容，而且您不會永久鎖定。
您仍然可以透過入口網站或以程序設計方式存取服務。 管理功能是透過訂用帳戶標識碼而非服務 API 金鑰運作，因此即使您的 API 金鑰不是，仍可供使用。
透過入口網站或管理層建立新的密鑰之後，一旦您在要求上提供這些密鑰之後，就會將存取權還原到您的內容（索引、索引器、數據源、同義字對應）。
保護 API 金鑰
使用角色指派來限制對 API 金鑰的存取。
您無法使用 客戶管理的金鑰加密來加密 API 金鑰。 只有搜尋服務本身內的敏感數據（例如，數據源物件定義中的索引內容或 連接字串）才能進行 CMK 加密。
在 Azure 入口網站 中流覽至您的搜尋服務頁面。
在左側瀏覽窗格中，選取 [訪問控制][IAM]，然後選取 [ 角色指派] 索引 標籤。
在 [ 角色 篩選] 中，選取有權檢視或管理密鑰的角色（擁有者、參與者、搜尋服務參與者）。 指派給這些角色之產生的安全性主體具有搜尋服務的主要許可權。
作為預防措施，也請檢查 [ 傳統系統管理員] 索引 標籤，以判斷系統管理員和共同管理員是否具有存取權。
最佳作法
只有在數據洩漏不具風險時，才使用 API 金鑰（例如，使用範例數據時），以及在防火牆後方操作時。 公開 API 金鑰是數據與未經授權使用搜尋服務的風險。
在發佈之前，請務必先檢查程式代碼、範例和訓練數據，以確保您未留下有效的 API 金鑰。
針對生產工作負載，切換至 Microsoft Entra 標識碼和角色型存取。 或者，如果您想要繼續使用 API 金鑰，請務必一律監視誰可以存取 API 金鑰，並定期重新產生 API 金鑰。