Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
利用 自訂 Web API 技能,呼叫提供自訂操作的 Web API 端點,來擴展 AI 豐富化。 像內建技能一樣, 自訂網頁 API 技能也有輸入和輸出。 根據輸入,當索引器執行時,你的 Web API 會收到一個 JSON payload,並以回應回傳一個 JSON payload 以及成功狀態碼。 回應必須包含你自訂技能指定的輸出。 任何其他的回應會被視為錯誤,並且不會執行任何擴充。 JSON 有效載荷的結構將在本文件後面說明。
自訂網頁 API 技能也用於 Azure OpenAI 的「你的資料」功能實作。 如果 Azure OpenAI 已設定為基於角色的存取,且建立向量索引時出現403 Forbidden錯誤,請確認 Foundry IQ(Azure AI 搜尋服務)是否擁有系統指派的身份,且在 Azure OpenAI 上作為受信任服務執行。
Note
針對從 Web API 傳回的特定標準 HTTP 狀態碼,索引子會重試兩次。 這些 HTTP 狀態碼為:
502 Bad Gateway503 Service Unavailable429 Too Many Requests
@odata.type
Microsoft.Skills.Custom.WebApiSkill
技能參數
參數區分大小寫。
| 參數名稱 | Description |
|---|---|
uri |
JSON 承載會傳送的目標 Web API URI。 僅允許 https URI 配置。 GET 與 LIST 回應會遮蔽敏感查詢值,包括 sig 和 code。 要更新技能而不更改儲存的 URI,請將整個 uri 設定為 <unchanged>。 關於回傳的佔位符與匹配規則,請參見 URI 遮蔽與憑證保留更新。 |
authResourceId |
(可選)一個字串,當設定時表示此技能應該在連接承載該程式碼的函式或應用程式時使用系統管理身份。 此屬性可將應用程式(用戶端)ID 或應用程式在 Microsoft Entra ID 中註冊,格式為 api://<appId>、 <appId>/.default、 或 api://<appId>/.default。 此值用於設定索引器取得的認證權杖範圍,並隨自訂 Web API 技能請求一同傳送至函式或應用程式。 設定此屬性需要將您的 Foundry IQ 服務設定為管理身份,且您的 Azure 函式應用程式已設定為 Microsoft Entra 登入。 要使用此參數,請呼叫 API api-version=2023-10-01-preview ,並啟用或之後。 關於如何選擇正確數值,請參見 「了解數 authResourceId 值」。 |
authIdentity |
(選用)由 Foundry IQ 服務用來連接承載程式碼的函式或應用程式的使用者管理身份。 您可以使用系統或使用者受控的識別。 若要使用系統受控識別,請保留 authIdentity 空白。 |
httpMethod |
傳送承載時使用的方法。 允許的方法為 PUT 和 POST |
httpHeaders |
機碼值組的集合,其中機碼代表標頭名稱,而值代表將與承載一起傳送至 Web API 的標頭值。 下列標頭禁止加入此集合:Accept、Accept-Charset、Accept-Encoding、Content-Length、Content-Type、Cookie、Host、TE, Upgrade、Via。 GET 和 LIST 回應會回傳 <redacted> 所有標頭值,以防止憑證(如承載憑證和 API 金鑰)被外洩。 若要保留同一技能與端點的儲存標頭值,請重新提交回傳 <redacted> 的值或使用 <unchanged>。 關於匹配規則,請參見 URI 塗黑與憑證保留更新。 |
timeout |
(選擇性) 指定時,表示進行 API 呼叫的 http 用戶端逾時。 其必須格式化為 XSD "dayTimeDuration" 值 ( ISO 8601 持續時間 值的受限子集)。 例如,PT60S 為 60 秒。 如果沒有設定,則選擇的預設值為 30 秒。 逾時最高可設定為 230 秒,最低 1 秒。 |
batchSize |
(選用) 指出每個 API 呼叫會傳送多少「資料記錄」(請參閱下面的 JSON 承載結構)。 如果未設定,則選擇的預設值為 1000。 利用這個參數在索引吞吐量與 API 負載之間取得適當的權衡。 |
degreeOfParallelism |
(選用) 指定時,指示索引子與您所提供的端點平行進行的呼叫數。 如果您的端點因壓力而失敗,則可以減少此值,或者,如果您的端點可以處理負載,則請增加此值。 若未設定,將會使用預設值 0.5。
degreeOfParallelism 最高可以設定為 10,最低為 1。 |
了解其 authResourceId 價值
當自訂 Web API 技能使用管理身份驗證時,Foundry IQ 會取得 Microsoft Entra 存取權杖並將其傳送至自訂技能端點。 該 authResourceId 屬性指定了請求令牌的資源識別碼,也稱為受眾或應用程式 ID URI。 該值必須符合目標應用程式在代幣驗證時的期望。 否則,驗證失敗且回應 401 Unauthorized 不佳。
這個 authResourceId 數值代表承載你自訂技能的應用程式。 它不是你的 Foundry IQ 服務或索引器的網址。
下表顯示常見格式:
| 目標應用程式 |
authResourceId 數值 |
|---|---|
| Microsoft Entra 受保護網頁應用程式 | api://<application-client-id> |
| 以自訂應用程式 ID URI 配置的應用程式 | 自訂應用程式識別碼 URI,例如 api://contoso-customskill |
| Azure Function 由 Microsoft Entra ID 保護 | 為功能應用程式的應用程式註冊所設定的應用程式 ID URI,例如 api://contoso-funcapp |
此屬性接受帶有及不帶 .default 範圍後綴的格式。 用 api://<appId> 來直接比對應用程式 ID 的 URI。 如果你加上 .default 後綴,例如 api://<appId>/.default,存取權杖的 aud 主張會包含沒有後綴的基礎應用程式 ID URI。
關於設定 Azure 函式 Microsoft Entra 驗證的authResourceId步驟,請參閱使用 Foundry IQ 服務管理身份連接至 Azure 函數應用程式。
範例:受 Microsoft Entra ID 保護的 Azure 函數
在此範例中,Foundry IQ 會為指定的 authResourceId 受眾取得存取權杖,並在呼叫自訂技能端點時包含該權杖。
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"uri": "https://contoso-function.azurewebsites.net/api/enrich",
"authResourceId": "api://contoso-customskill"
}
技能輸入
此技能沒有預設輸入。 輸入是任何現有欄位,或您想要傳遞至自訂技能之擴充樹狀結構中的任何節點。
技能產出
此技能沒有預設輸出。 如果技能的輸出應該傳送至搜尋索引中的欄位,則請務必在索引子中定義輸出欄位對應。
範例定義
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "A custom skill that can identify positions of different phrases in the source text",
"uri": "https://contoso.count-things.com",
"batchSize": 4,
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "language",
"source": "/document/languageCode"
},
{
"name": "phraseList",
"source": "/document/keyphrases"
}
],
"outputs": [
{
"name": "hitPositions"
}
]
}
URI 遮蔽與憑證保留更新
這種 URI 查詢行為適用於所有 API 版本。
當您以 GET 取得技能組或使用 LIST 擷取清單技能集時,Foundry IQ 會遮蔽敏感的自訂 Web API 技能(WebApiSkill) URI 查詢值,包括 sig 和 code、 及 HTTP 標頭值。 這些已遮蔽的值保護共享存取簽章(SAS)簽章、功能鍵及標頭憑證。
對於新增技能或複製的技能,請提供目標端點所需的查詢與標頭密鑰,或設定支援的管理式身份驗證與授權。 回傳 <redacted> 和 <unchanged> 佔位符並不是憑證。
若要保留儲存的密鑰,請在同一端點更新相同的現有技能組合及匹配的自訂 Web API 技能。 保留標頭必須與現有標頭名稱相符,且服務必須識別一個明確的來源技能。 提交管理 PUT 請求的完整技能組定義中所回傳 <redacted> 或 <unchanged> 佔位符。 此 PUT 更新了技能組定義;這不是由技能 httpMethod控制的終點召喚。 你也可以設定整個 uri to <unchanged> 來保留儲存的 URI。
變更端點需要明確的目標憑證;儲存的機密不會被轉移。
如果服務無法辨識一個明確且明確的現有來源作為佔位符,PUT 就會 400 Bad Request 失敗並要求實際的秘密值。 未解決或持續存在的佔位符並不是可用的憑證。 秘密還原是原子性的:失敗的還原不會部分套用 URI 或標頭變更。
你可以隨時提供替代的 URI 或標頭秘密。 明確的值優先於佔位符。
URI 查詢更新遵循以下規則:
- 對於 Azure 函式
code參數,你可以更新其他非秘密查詢參數,同時保留同一端點的函式金鑰。 - 對於 SAS
sig參數,簽名綁定於周圍的非秘密查詢配置。 若範圍、權限、到期日、資源、版本、排序、格式或編碼有變更,則提供新的簽章。 即使是語意等價的重新排序或重新編碼的查詢文字,也需要新的簽章。
秘密查詢參數名稱可不區分大小寫且以百分比編碼方式識別。 該服務會保留你的 URI 表示,而不是將其標準化。 重複的祕密參數會依出現頻率來匹配。 如果它們的出現模式不再與儲存的 URI 對齊,請提供實際值。
現有的 GET-then-PUT 工作流程仍在使用 <redacted> 或 <unchanged> 持續支援。
關於查詢時向量化,請參見 自訂 Web API 向量化工具 URI 遮蔽及憑證保留更新。
以下的 GET 回應會刪除函式鍵與標頭值。 要保留這些數值,請更新相同的技能和終點。
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"uri": "https://contoso.example.org/api?code=<redacted>",
"httpMethod": "POST",
"name": "myCustomSkill",
"httpHeaders": {
"Authorization": "<redacted>",
"Ocp-Apim-Subscription-Key": "<redacted>"
}
}
若要保留整個 URI 及現有標頭值,請在同一技能的完整定義中使用 <unchanged> 這些屬性。 以下片段並非獨立的建立或更新請求:
{
"uri": "<unchanged>",
"httpHeaders": {
"Authorization": "<unchanged>",
"Ocp-Apim-Subscription-Key": "<unchanged>"
}
}
關於參數細節,請參見 技能參數。
這些規則適用於自訂 Web API URI 與標頭屬性,而非所有攜帶秘密的技能。 如需安全的匯出及相依性重建序列,請參閱 備份、還原或複製索引。
範例輸入 JSON 結構
這個 JSON 結構代表你傳送給 Web API 的有效載荷。 它一律會遵循下列這些條件約束:
最上層的實體稱為
values,且是物件的陣列。 這些物件的數量最多batchSize為 。values陣列中的每個物件都具有:一個
recordId唯一 字串的 屬性,用來識別該紀錄。一個
data屬性是 JSON 物件。 屬性的data欄位會對應至技能定義區inputs段中指定的「名稱」。 這些欄位的數值來自這些欄位中的 (source可以是文件中的某個欄位,或可能是其他技能)。
{
"values": [
{
"recordId": "0",
"data":
{
"text": "Este es un contrato en Inglés",
"language": "es",
"phraseList": ["Este", "Inglés"]
}
},
{
"recordId": "1",
"data":
{
"text": "Hello world",
"language": "en",
"phraseList": ["Hi"]
}
},
{
"recordId": "2",
"data":
{
"text": "Hello world, Hi world",
"language": "en",
"phraseList": ["world"]
}
},
{
"recordId": "3",
"data":
{
"text": "Test",
"language": "es",
"phraseList": []
}
}
]
}
範例輸出 JSON 結構
「輸出」對應至從您的 Web API 傳回的回應。 Web API 應該只傳回 JSON 承載 (透過查看 Content-Type 回應標頭進行驗證),並且應該滿足下列限制式:
應該有一個名為
values的最上層實體,它應該是物件陣列。陣列中的物件數目應該與傳送至 Web API 的物件數目相同。
每個物件都應該有:
recordId屬性。data屬性,它是一個物件,其中的欄位是與output中的「名稱」相符的擴充,其值會被視為擴充。errors屬性,一個會新增至索引子執行歷程記錄中的陣列,其中列出發生的任何錯誤。 此屬性是必要的,但可以具有null值。warnings屬性,一個會新增至索引子執行歷程記錄中的陣列,其中列出發生的任何警告。 此屬性是必要的,但可以具有null值。
要求或回應中
values內的物件順序並不重要。 不過,recordId用於相互關聯,因此包含recordId(不是 Web API 的原始要求的一部分) 的回應中的任何記錄都會捨棄。
{
"values": [
{
"recordId": "3",
"data": {
},
"errors": [
{
"message" : "'phraseList' should not be null or empty"
}
],
"warnings": null
},
{
"recordId": "2",
"data": {
"hitPositions": [6, 16]
},
"errors": null,
"warnings": null
},
{
"recordId": "0",
"data": {
"hitPositions": [0, 23]
},
"errors": null,
"warnings": null
},
{
"recordId": "1",
"data": {
"hitPositions": []
},
"errors": null,
"warnings": [
{
"message": "No occurrences of 'Hi' were found in the input text"
}
]
}
]
}
錯誤案例
除了你的 Web API 無法使用或傳送不成功的狀態碼外,以下情況也可視為錯誤:
如果 Web API 回傳成功狀態碼,但回應顯示未
application/json成功,則回應無效且未進行任何豐富化。如果回應
values陣列包含無效紀錄(例如缺失或重複recordId),這些無效紀錄不會被豐富。 在開發自訂技能時,請遵守 Web API 技能合約。 您可以參考此範例,其提供於遵循預期合約的 Power Skill 存放庫。
當 Web API 無法使用或回傳 HTTP 錯誤時,索引器的執行歷史會包含一個友善錯誤,並包含所有可用的 HTTP 錯誤細節。
管理身份驗證的安全考量
當使用管理式身分驗證搭配自訂 Web API 技能時,Foundry IQ 會取得 Microsoft Entra 存取權杖,用於由 所識別authResourceId的應用程式,並將該權杖包含在寄送至 由 指定的uri端點的請求中。 所uri參考的端點通常是你的 Azure Function、Azure App 服務、Azure API 管理 端點,或其他受 Microsoft Entra 保護的應用程式。 你負責配置並維護端點與應用程式 authResourceId之間的關係。
無論驗證方式為何,自訂技能輸入可能包含客戶提供文件的數值,或是從這些文件衍生出的數值。 把所有自訂技能輸入都當作不可信。 Foundry IQ 會將技能集中配置的輸入傳送至您的端點,無需解讀、驗證或限制其內容以供自訂實作使用。
在使用文件衍生值於外站請求或其他安全敏感操作前,請先驗證並限制自訂技能中的文件衍生值。 使用輸入驗證、目的地允許清單、URL 與主機名稱驗證、協定限制,以及只允許該技能所需的目的地與埠的最低權限網路存取。 欲了解更多資訊,請參閱網路 與連接架構策略。
建議的安全性做法
為維持部署安全,請遵循以下做法:
- 設定屬性
uri僅指向用於接收來自 Foundry IQ 請求的受信任端點。 - 設定
authResourceId以識別預期會接收並驗證存取權杖的 Microsoft Entra 應用程式。 - 確保接收請求的應用程式在處理請求前,先驗證標準令牌主張,包括受眾(
aud)、發行者(iss)、租戶(tid)、以及任何必要的應用程式角色或權限。 - 授予 Foundry IQ 管理身份權限時,請採用最小權限原則。
- 定期檢視自訂 Web API 技能定義、Microsoft Entra 應用程式註冊,以及授予 Foundry IQ 管理身份的應用程式角色指派與權限。 透過您已建立的變更管理與安全審查流程來審查組態變更。
- 定期檢視 Azure Functions、App Services、API 及 API 閘道的端點設定。
- 監控應用程式登入日誌、認證事件及 API 存取日誌,防止意外或未經授權的活動。
- 移除不再需要的端點、權限、應用程式註冊及角色指派。
限制技能組設定的存取
能建立、修改或執行技能組的使用者,可以同時控制目的地端點以及自訂 Web API 技能所使用的認證設定。 將這些權限限制給受信任的管理員,並在配置管理身份啟用自訂技能時,遵循標準的變更管理與安全審查流程。
Important
該 authResourceId 值用以識別存取權杖的預定接收應用程式。 確保該 uri 端點是預期接收並驗證該應用程式權杖的端點。 錯誤的設定可能導致認證失敗或請求傳送到非預期端點。