Foundry IQ(Azure AI 搜尋服務)支援基於身份與金鑰的驗證(預設)以連接您的 Foundry IQ 服務。
若對 Foundry IQ 服務端點的請求與 API 金鑰皆有效,且 Foundry IQ 服務已設定允許在請求上使用 API 金鑰,該請求即被接受。
重要事項
當您建立 Foundry IQ 服務時,預設採用金鑰驗證,但這並非最安全的選項。 我們建議您將其取代為角色型存取。
先決條件
您必須是擁有者、貢獻者或 搜尋服務貢獻 者才能查看或管理鑰匙。
預設為啟用
在Azure入口網站中,認證是在 Settings>Keys頁面指定。 選項設為 API 金鑰 (預設) 或兩者,允許在要求上使用 API 金鑰。
金鑰的類型
API 金鑰是由 52 個隨機產生的數字和字母所組成的唯一字串。 管理金鑰或查詢金鑰在外觀上並無差別。 如果你忘記應用程式中指定了哪種金鑰,可以在Azure入口網站 檢查金鑰值。
有兩種金鑰可用來驗證要求:
| 類型 |
權限等級 |
它是如何被創造的 |
最大值 |
| 管理 |
所有資料平面 (內容) 作業的完整存取權 (讀寫)。 |
服務建立時會產生兩個管理密鑰,主密鑰與次要密鑰,並可按需分別重新生成。 具備兩個可讓您在使用第二個金鑰持續存取服務的同時,將其中一個金鑰輪替更新。 |
2 |
| 查詢 |
唯讀存取權,範圍設定為搜尋索引的文件集合 |
服務會產生一個查詢金鑰。 Foundry IQ 服務管理員可按需建立更多。 |
50 |
尋找現有的金鑰
你可以使用 Azure portal、PowerShell、Azure CLI 或 REST API 來查看和管理 API 金鑰。
前往 Azure 入口網站中的 Foundry IQ 服務。
從左側窗格選擇 設定>鍵 以查看管理員鍵與查詢鍵。
執行以下指令可分別取得管理員與查詢 API 金鑰。 如需 REST 協助,請參閱 使用 REST API 管理您的 Foundry IQ 服務。
傳回系統管理金鑰:
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2025-05-01
傳回查詢金鑰:
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2025-05-01
參考:Admin Keys - Get, Query Keys - List By Search Service
使用 Azure SDK for Python 來程式化取得 API 金鑰。 安裝管理 SDK:
pip install azure-mgmt-search azure-identity
執行以下程式碼以返回管理員與查詢 API 金鑰:
import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.search import SearchManagementClient
# Set up variables
subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"]
resource_group = "your-resource-group"
search_service_name = "your-search-service"
# Create the management client
credential = DefaultAzureCredential()
client = SearchManagementClient(credential, subscription_id)
# Get admin keys
admin_keys = client.admin_keys.get(resource_group, search_service_name)
print(f"Primary admin key: {admin_keys.primary_key}")
print(f"Secondary admin key: {admin_keys.secondary_key}")
# Get query keys
query_keys = client.query_keys.list_by_search_service(resource_group, search_service_name)
for key in query_keys:
print(f"Query key '{key.name}': {key.key}")
參考:SearchManagementClient | AdminKeys | QueryKeys
執行以下指令可分別取得管理員與查詢 API 金鑰。 如需 PowerShell 協助,請參閱 使用 PowerShell 管理您的 Foundry IQ 服務。
安裝 Az.Search 模組:
Install-Module Az.Search
傳回系統管理金鑰:
Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>
傳回查詢金鑰:
Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>
執行以下指令可分別取得管理員與查詢 API 金鑰。 如需使用 Azure CLI 的協助,請參閱「使用 Azure CLI 管理您的 Foundry IQ 服務」。
傳回系統管理金鑰:
az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>
傳回查詢金鑰:
az search query-key list --resource-group <myresourcegroup> --service-name <myservice>
在連接中使用金鑰
基於金鑰的認證僅用於資料平面(內容)請求,例如建立或查詢索引,以及使用 搜尋服務 REST API 執行的其他操作。
在你的原始碼中,你可以直接在請求標頭指定 API 金鑰。 或者,你也可以把它當作 環境變數 或應用程式設定存在專案裡,然後在請求中引用該變數。
- 系統管理金鑰可用來建立、修改或刪除物件。
- 管理金鑰也用於 GET 物件定義和系統資訊,例如 LIST 索引 或 GET 服務統計資料。
- 查詢金鑰通常會散發給發出查詢的用戶端應用程式。
回想一下,金鑰驗證預設為啟用,並支援索引和查詢等資料平面作業。
不過,如果您停用 API 金鑰,並設定角色指派,Azure 入口網站就會改用角色指派。
在要求標頭中設定系統管理金鑰。 您無法在 URI 或要求主體中傳遞系統管理金鑰。
以下是在建立索引要求上使用系統管理 API 金鑰的範例:
@baseUrl=https://my-demo-search-service.search.windows.net
@adminApiKey=aaaabbbb-0000-cccc-1111-dddd2222eeee
### Create an index
POST {{baseUrl}}/indexes?api-version=2026-10-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=2026-10-01&api-key={{queryApiKey}}
附註
在要求 URI 中傳遞敏感性資料 (例如 api-key) 被視為不佳的安全性做法。 因此,Foundry IQ 只接受查詢鍵作為查詢字串中的 api-key。 一般規則是建議將 api-key 當作要求標頭來傳遞。
最佳做法是將 API 金鑰設定為環境變數,但為了簡單起見,此範例將其顯示為字串。 此範例會針對查詢作業使用查詢 API 金鑰。
# Import libraries
from azure.search.documents import SearchClient
from azure.core.credentials import AzureKeyCredential
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts
# Variables for endpoint, keys, index
search_endpoint: str = "https://<Put your search service NAME here>.search.windows.net/"
credential = AzureKeyCredential("Your search service query key")
index_name: str = "hotels-quickstart-python"
# Set up the client
search_client = SearchClient(endpoint=search_endpoint,
index_name=index_name,
credential=credential)
# Run the query
results = search_client.search(query_type='simple',
search_text="*" ,
select='HotelName,Description,Tags',
include_total_count=True)
print ('Total Documents Matching Query:', results.get_count())
for result in results:
print(result["@search.score"])
print(result["HotelName"])
print(result["Tags"])
print(f"Description: {result['Description']}")
使用下列語法在要求標頭中設定 API 金鑰:
$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json'
'Accept' = 'application/json' }
使用變數來儲存完全限定的查詢語句。
$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2026-10-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'
將請求傳送至 Foundry IQ 服務:
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
更多其他操作的腳本範例可參見《 快速入門:使用 REST API 在 PowerShell 中建立 Foundry IQ 索引》。
建立查詢金鑰
查詢金鑰針對以文件集合為目標的作業,用於唯讀存取索引內的文件。 搜尋、篩選和建議查詢全都是採用查詢金鑰的作業。 任何傳回系統資料或物件定義的唯讀作業 (例如索引定義或索引子狀態) 都需要系統管理金鑰。
限制用戶端應用程式中的存取和作業是保護服務上搜尋資產的必要條件。 請一律針對源自用戶端應用程式的任何查詢使用查詢金鑰,而非使用系統管理員金鑰。
前往 Azure 入口網站中的 Foundry IQ 服務。
從左側窗格選擇 設定>金鑰 以查看 API 金鑰。
在 [管理查詢金鑰] 下,使用已為您服務產生的查詢金鑰,或建立新的查詢金鑰。 預設查詢金鑰並未命名,但可命名其他產生的查詢金鑰以方便管理。
在管理 REST API 中使用建立查詢金鑰。
您必須擁有有效的角色分配才能建立或管理 API 金鑰。 請參閱 〈使用 REST API 管理您的 Foundry IQ 服務 〉,了解如何使用 REST API 滿足角色需求。
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2025-05-01
重新產生系統管理金鑰
針對每個服務,會建立兩個系統管理金鑰,讓您可以輪換主要金鑰,同時使用次要金鑰以獲得業務持續性。
前往 Azure 入口網站中的 Foundry IQ 服務。
從左窗格中,選取 [設定]>[金鑰]。
複製副鑰匙。
針對所有的應用程式,更新 API 金鑰設定以使用次要金鑰。
重新產生主要金鑰。
更新所有應用程式以使用新的主要金鑰。
如果您不小心同時重新產生這兩個金鑰,則使用這些金鑰的所有用戶端要求都會失敗,並發生 HTTP 403 禁止。 不過,並不會刪除內容,且不會將您永久鎖定。
你仍然可以透過 Azure 入口網站或程式化方式存取這項服務。 管理功能是透過訂用帳戶識別碼而非服務 API 金鑰運作,因此即使您的 API 金鑰無法使用,管理功能仍可使用。
透過入口網站或管理層建立新的金鑰之後,一旦您依要求提供這些金鑰,存取權就會還原至您的內容 (索引、索引子、資料來源、同義字對應)。
從金鑰遷移到角色
若要將基於金鑰的存取轉換為基於角色的存取,請使用以下角色指派:
重要事項
Search Service Contributor 是一個控制平面角色,可以取得管理員金鑰,提供對資料平面的完整讀寫存取權限。 只把這個角色授予值得信賴的使用者。
安全金鑰
使用角色指派來限制對 API 金鑰的存取。
您無法使用客戶自控金鑰加密來加密 API 金鑰。 只有 Foundry IQ 服務本身內的敏感資料(例如資料來源物件定義中的索引內容或連線字串)才能進行 CMK 加密。
前往 Azure 入口網站中的 Foundry IQ 服務。
從左側窗格選擇 存取控制(IAM),然後選擇 角色指派 標籤。
在 [角色] 篩選條件中,選取有權檢視或管理金鑰的角色 (擁有者、參與者、搜尋服務參與者)。 指派給這些角色的產生安全主體對您的 Foundry IQ 服務具有關鍵權限。
作為預防措施,也請檢查 [傳統管理員] 索引標籤,以判斷管理員和共同管理員是否具有存取權。
最佳作法
相關內容