Azure IoT 操作 MCP 提供可用來讀取文件、檢視已部署的資源、擷取結構描述、取樣 MQTT 訊息、讀取 State Store 中的值,以及發佈 MQTT 訊息的工具。 本文說明內建工具、它們的論點、結果與限制。
Important
Azure IoT 操作 中的 MCP 目前處於預覽階段。 請使用非生產環境來評估預覽及以下範例。 發布 MQTT 訊息可能會觸發後續動作。
工具索引
| Category | Tools |
|---|---|
| Documentation | documentation_overview, 說明文件 |
| Assets | list_assets, get_asset, asset_details |
| Devices | list_devices、 get_device、 device_details |
| 代理程式 | list_brokers、 get_broker、 broker_details、 broker_metadata |
| Connectors | list_connectors, get_connector, connector_details, find_connector_by_device |
| 數據流 | list_dataflows、 get_dataflow、 dataflow_details |
| 資料流程圖 | list_dataflow_graphs、 get_dataflow_graph、 dataflow_graph_details |
| Edge Registry | list_edge_registry_groups、 get_edge_registry_group、 list_edge_registry_resources、 list_edge_registry_resource_versions、 get_edge_registry_resource、 get_edge_registry_generic_resource、 get_edge_registry_schema_from_asset |
| MQTT 資料 | mq_messages, mqtt_publish |
| 狀態儲存 | dss_get |
開始之前
- 部署 MCP 並 連接相容 MCP 的用戶端。
-
為您想呼叫的工具設定 MCP 授權。 預設
Reader角色涵蓋文件與資源檢查工具;DataReader涵蓋mq_messages及dss_get。 對於代理商的中繼資料,請依照 「啟用代理中繼資料存取權 」以指派Admin給受信任客戶端;在預設原則下,此角色也允許所有其他後端工具,包括寫入工具。 僅為發佈時,請設定專用的工具授權。 - 確認後端的下游權限。 MCP 角色不授予 Kubernetes 讀取權限、MQTT 訂閱或發佈權限、狀態儲存庫存取權或邊緣登錄權限。
透過預設 aio 連線,用戶端會看到像 aio_list_assets這樣的名稱。 授權政策使用未前綴的名稱,例如 list_assets。 對於其他連線名稱,請使用該連線的前綴。 工具發現會依照呼叫者的政策進行篩選,如果後端沒有 broker 連線,有些工具就不會被註冊。 自訂後端設定可以新增或變更工具。 使用用戶端的工具探索來檢查可用的名稱與結構描述。
說明文件工具
這些唯讀工具會回傳嵌入在後端映像中的文件。 這些工具不會搜尋網路,也不保證最新的線上內容。 他們不需要存取你的應用程式資料。
文件概觀
擷取文件目錄以尋找文章的相對 href。 例如,請您的代理程式在取得 broker 授權說明文件前先找到該文件。
這個工具沒有任何參數。 呼叫 aio_documentation_overview:
{}
結果範例(節錄):
{
"items": [
{
"href": "index.yml",
"items": [
{
"name": "Overview",
"href": "overview-iot-operations.md"
}
]
}
]
}
實際的樹可以包含巢狀 items 陣列。 項目可以包含 name、display_name 和 href;分組節點可能沒有 href。 追蹤子項目以尋找頁面。 此樹中缺少的文章可能未嵌入於已安裝的後端版本中。
文件
在使用 documentation_overview 找到一篇嵌入文章的相對路徑後,擷取該文章。
| Argument | Required | Meaning |
|---|---|---|
href |
Yes | 文件目錄中的精確相對路徑。 |
呼叫 aio_documentation:
{
"href": "overview-iot-operations.md"
}
結果範例(節錄):
{
"body": "---\ntitle: What Is Azure IoT Operations?\n"
}
body 包含文章內容,包括 Markdown 及任何前置說明。 它不是摘要或渲染出來的 HTML。 請使用嵌入路徑,而非絕對的網站網址。 未知路徑會傳回錯誤,而非空文章。
Kubernetes 資源檢查工具
下列工具會讀取後端在其已設定命名空間範圍內可看見的資源類型。 他們不會修改資源或回傳歷史紀錄。 後端需要具備 Kubernetes 中每種資源類型的讀取權限。
-
list工具會回傳一個以程式化資源名稱為鍵的物件,而非
items陣列。 值在已設定時為描述,或為true以表示存在。 這不是一個啟用或健康的旗標。 空物件表示後端的範圍不包含任何資源。 -
get 工具通常回傳資源資料,通常是
spec和status,而非完整的 Kubernetes API 封裝格式。 當細節工具無法顯示你需要的資訊時,就使用它。 缺少資源或 Kubernetes 請求失敗即屬錯誤。 -
details 工具接受一組名稱及一個細節選擇器。 對於一個名稱,結果直接為該細節物件;標量則包裹在該細節名稱之下。 對於多個名稱,結果會以資源名稱為鍵。 遺漏或無法取得的細節可以省略;
{}這並不代表該資源是健康的或無錯誤的。 使用 get 工具來調查。 不支援的詳細選擇器會傳回錯誤訊息。
列出工具不接受資源名稱參數或分頁參數。 詳細陣列包含精確的資源名稱,而非萬用字元模式。 狀態欄位反映控制器最後的報告,可能會落後於當前狀況。
list_assets
在檢查資產、其目的地或資料集結構之前,先了解資產名稱。 不需要任何參數。
呼叫 aio_list_assets:
{}
範例結果:
{
"oven": "Production oven telemetry"
}
描述來自資產的描述或顯示名稱。 沒有字串描述的資源值為 true。 在 asset_details、get_edge_registry_schema_from_asset 和 get_asset 中,請使用物件鍵,而非描述。 此清單不讀取資產遙測數據。
get_asset
讀取資產的設定與回報狀態,包括資料集、裝置參考及目的地。 使用 asset_details 查看支援的詳細資料。
| Argument | Required | Meaning |
|---|---|---|
asset |
Yes | 精確的資產名稱來自 list_assets。 |
撥打 aio_get_asset:
{
"asset": "oven"
}
結果範例(節錄):
{
"spec": {
"enabled": true
}
}
檢查 spec.datasets 已設定的資料集名稱及 status.datasets 回報的訊息結構參考。 這些資料集不一定同時被填入。 回應描述的是設定與狀態,而非目前的資料集數值。 不存在的資產會回傳錯誤訊息。
asset_details
讀取一個或多個資產的選取資訊,而不必擷取每個完整設定。
| Argument | Required | Meaning |
|---|---|---|
assets |
Yes | 一組精確的資產名稱。 |
detail |
Yes |
customer_metadata、destinations、device、enabled、errors或health_status。 |
呼叫 aio_asset_details:
{
"assets": ["oven"],
"detail": "enabled"
}
範例結果:
{
"enabled": true
}
customer_metadata 包含識別碼以及製造商、型號、修訂版或序號欄位(如有)。
destinations 依資料運算子與名稱將目的地群組,使用第一個設定的目的地或其預設值。
device 會傳回裝置參考。
errors 和 health_status 使用回報的狀態,而該狀態可能不存在。 將名稱加入 assets,以取得可供比較的名稱鍵控結果。
list_devices
在讀取裝置的設定、端點或連接器分配之前,先了解裝置名稱。 不需要任何參數。
呼叫 aio_list_devices:
{}
範例結果:
{
"oven-device": true
}
這些鍵是 Kubernetes 裝置資源名稱,而不是端點名稱或外部裝置 ID。
true 僅表示存在。 將鍵傳遞至 get_device、 device_details、 或 find_connector_by_device。 結果為空也可能表示您正在檢查沒有裝置的命名空間。
get_device
讀取裝置的設定與回報狀態,包括其入站與出站端點。 使用 device_details 表示支援的詳細資料。
| Argument | Required | Meaning |
|---|---|---|
device |
Yes | 精確的裝置資源名稱。 |
呼叫 aio_get_device:
{
"device": "oven-device"
}
結果範例(節錄):
{
"spec": {
"enabled": true
}
}
端點設定可以包含位址、驗證方法以及秘密參考。 將回傳的設定視為可能敏感;此工具並非用來擷取參考的秘密值。 狀態會在可用時顯示端點層級健康狀態和錯誤。 裝置的存在並不代表其終端是可連線的。
device_details
在一個或多個裝置上讀取所選裝置屬性。
| Argument | Required | Meaning |
|---|---|---|
devices |
Yes | 精確的裝置資源名稱陣列。 |
detail |
Yes |
customer_metadata、enabled、endpoints、errors,或health_status。 |
撥打 aio_device_details:
{
"devices": ["oven-device"],
"detail": "enabled"
}
範例結果:
{
"enabled": true
}
endpoints群組端點位址及驗證方法名稱依方向與端點名稱分組。
customer_metadata 會傳回外部 ID、製造商、型號及作業系統資訊。 裝置健康狀況是依各個端點回報,而不是單一的根層級健康值。 錯誤輸出為空或健康狀態輸出可能代表狀態未被回報。 在下結論前先檢查 get_device。
list_brokers
找出後端範圍內的 broker 資源名稱。 你不需要提供任何引數。
呼叫 aio_list_brokers:
{}
範例結果:
{
"default": true
}
將回傳的名稱與 get_broker 或 broker_details 一起使用。
true 但這不代表代理程式健康。 此工具列出代理資源,而非其分割區、複本、MQTT 會話或監聽器。 使用 broker_metadata 來查看即時會話與佇列資訊。
get_broker
讀取代理程式設定及回報狀態,包括基數限制與診斷設定。
| Argument | Required | Meaning |
|---|---|---|
broker |
Yes | 經紀人資源的精確名稱。 |
呼叫 aio_get_broker:
{
"broker": "default"
}
結果範例(節錄):
{
"spec": {
"cardinality": {
"backendChain": {
"partitions": 2,
"workers": 2
}
}
}
}
回應描述的是代理資源,而非獨立的 BrokerListener 或 BrokerAuthorization 資源。 僅用於 broker_details 健康。 設定基數不是連接 MQTT 用戶端的數量;請使用元資料工具檢查會話。
broker_details
讀取一位或多位經紀人的最後回報的健康狀況。
| Argument | Required | Meaning |
|---|---|---|
brokers |
Yes | 完全相符的經紀商名稱陣列。 |
detail |
Yes |
health_status。 |
撥打 aio_broker_details:
{
"brokers": ["default"],
"detail": "health_status"
}
結果範例(節錄):
{
"status": "Available",
"message": "",
"reasonCode": ""
}
健康可以包含 lastTransitionTime 和 lastUpdateTime。 它報告的是控制器的整體狀態,而非端對端的 MQTT 事務測試。 缺失的健康資料可以產生 {};請使用 get_broker 和操作診斷進行調查。
list_connectors
在檢查其健康狀態或配置之前,先發現已實例化的連接器資源名稱。 不需要任何參數。
呼叫 aio_list_connectors:
{}
範例結果:
{
"opcua-connector": true
}
名稱用於識別連接器實例,而非連接器範本或裝置端點。 與 get_connector 和 connector_details 一起使用。 若要從裝置開始反向操作,請使用 find_connector_by_device。 僅僅存在並不代表連接器有目前的裝置分配。
get_connector
讀取連接器資源的設定與回報狀態。
| Argument | Required | Meaning |
|---|---|---|
connector |
Yes | 精確的連接器實例名稱。 |
呼叫 aio_get_connector:
{
"connector": "opcua-connector"
}
結果範例(節錄):
{
"status": {
"runtime": {
"output": {
"allocatedDevices": [
{
"deviceName": "oven-device",
"deviceInboundEndpointName": "opcua"
}
]
}
}
}
}
執行時配置是回報的狀態,可能缺失或已過時。 當您只需要健康值或分配欄位時使用 connector_details 。 此工具不會連接裝置、不會重新啟動連接器,也不會驗證端點憑證。
連接器詳細資料
讀取連接器健康狀態、執行時裝置配置,或兩者皆可。
| Argument | Required | Meaning |
|---|---|---|
connectors |
Yes | 精確連接器名稱陣列。 |
detail |
Yes |
health_status、runtime_device_allocation 或 status。 |
呼叫 aio_connector_details:
{
"connectors": ["opcua-connector"],
"detail": "runtime_device_allocation"
}
結果範例(節錄):
{
"allocatedDevices": [
{
"deviceName": "oven-device",
"deviceInboundEndpointName": "opcua"
}
]
}
分配輸出也可以包含一個 timestamp。
status 選擇器結合了 runtimeDeviceAllocation 和 healthStatus。
health_status 選擇器僅回傳健康狀態。 配置欄位缺失並不代表裝置未指派:連接器可能尚未回報執行狀態。
find_connector_by_device
尋找其報告的執行時分配包含裝置的連接器。 可選擇一個入站端點,以消除具有多個端點的裝置的歧義。
| Argument | Required | Meaning |
|---|---|---|
device_name |
Yes | 裝置資源名稱;不得為空。 |
device_inbound_endpoint_name |
No | 精確的入站端點名稱;若提供,不得為空。 |
呼叫 aio_find_connector_by_device:
{
"device_name": "oven-device",
"device_inbound_endpoint_name": "opcua"
}
結果範例(節錄):
{
"matches": [
{
"connectorName": "opcua-connector",
"runtime": {
"output": {
"allocatedDevices": [
{
"deviceName": "oven-device",
"deviceInboundEndpointName": "opcua"
}
]
}
}
}
]
}
匹配會忽略裝置名稱與端點名稱的大小寫。 每個匹配都包含匹配的分配項目,並可包含 healthState 及 執行時間戳記。
{"matches":[]} 表示未找到相符的已回報配置;這不是即時端點連線檢查。 省略可選的端點參數,以搜尋該裝置的所有入站端點。
list_dataflows
在檢視其配置或健康狀況之前,先了解資料流資源名稱。 不需要任何參數。
呼叫 aio_list_dataflows:
{}
範例結果:
{
"oven-dataflow": true
}
結果包含資源名稱,而非資料流程設定檔名稱或端點名稱。
true 表示存在,即使流程被停用或狀態不佳。 使用 get_dataflow 查看其來源和目的地設定,或使用 dataflow_details 查看回報的健康狀態。
get_dataflow
閱讀單一資料流的設定及回報狀態。
| Argument | Required | Meaning |
|---|---|---|
dataflow |
Yes | 精確的資料流資源名稱。 |
呼叫 aio_get_dataflow:
{
"dataflow": "oven-dataflow"
}
結果範例(節錄):
{
"spec": {
"mode": "Enabled"
}
}
spec.operations 描述已設定的來源、轉換和目的地作業。 這個工具不會執行流程,也不會回傳通過流程的訊息。 端點參考是用來描述個別資源,且不包含其完整設定。 使用 dataflow_details 以取得較小、僅含健康狀態的結果。
dataflow_details
讀取一個或多個資料流的報告健康狀態。
| Argument | Required | Meaning |
|---|---|---|
dataflows |
Yes | 精確資料流程名稱的陣列。 |
detail |
Yes |
health_status。 |
呼叫 aio_dataflow_details:
{
"dataflows": ["oven-dataflow"],
"detail": "health_status"
}
結果範例(節錄):
{
"status": "Available",
"message": "",
"reasonCode": ""
}
對單一流程,健康欄位會直接回傳;對多個流程而言,則以名稱作為鍵。 健康狀況可以包含報告時間和轉換時間。 現有報告無法證明某則訊息是否已送達目的地;請另行測試投遞。 狀態缺失可能導致結果為空。
list_dataflow_graphs
探索資料流程圖的名稱。 這些資源與由 list_dataflows返回的資料流是分開的。 你不需要提供任何參數。
呼叫 aio_list_dataflow_graphs:
{}
範例結果:
{
"oven-graph": true
}
使用帶有 get_dataflow_graph 或 dataflow_graph_details 的圖例鍵。 圖形的存在並不代表它已啟用或健康。 此工具不會列舉單一圖表節點。 擷取這些項目的圖表設定。
get_dataflow_graph
讀取圖形的配置與已回報狀態,包括節點及節點連線。
| Argument | Required | Meaning |
|---|---|---|
dataflowGraph |
Yes | 精確的圖形資源名稱。 這個引數使用駝峰式命名。 |
呼叫 aio_get_dataflow_graph:
{
"dataflowGraph": "oven-graph"
}
結果範例(節錄):
{
"spec": {
"mode": "Enabled"
}
}
若要依照已設定的處理路徑操作,請檢查 spec.nodes 和 spec.nodeConnections。 回應不是單一訊息的追蹤記錄或執行預覽。 如果您只需要圖表所報告的健康狀況,請使用 dataflow_graph_details 。
dataflow_graph_details
讀取一個或多個資料流程圖的回報健康狀態。
| Argument | Required | Meaning |
|---|---|---|
dataflowGraphs |
Yes | 精確圖表名稱陣列。 這個引數使用駝峰命名法。 |
detail |
Yes |
health_status。 |
呼叫 aio_dataflow_graph_details:
{
"dataflowGraphs": ["oven-graph"],
"detail": "health_status"
}
結果範例(節錄):
{
"status": "Available",
"message": "",
"reasonCode": ""
}
健康狀況描述的是圖表控制器所報告的狀態,而非逐節點的訊息內容。 缺失健康狀態可能導致 {}。 將報告時間戳與調查時間進行比較,並使用取得工具取得設定上下文。
Edge Registry 工具
這些唯讀工具透過後端的 Edge 登錄用戶端擷取元資料與文件。 它們需要已設定的代理程式連線以及對 Edge 登錄服務的下游存取。 會使用後端的身份,而非 MCP 呼叫者的 MQTT 身份。
類型工具使用 resource_kind: schema、、 thing_description或 thing_model。 通用工具則改用 xRegistry 集合名稱,例如 schemagroups 和 schemas。 請勿以 Kubernetes 命名空間或資產名稱替代登錄群組 ID。
除非另有指定,省略 group_id 會選取雲端預設群組。 對於資源與版本清單,all_groups: true 會搜尋所有群組;請勿將其與 group_id 一起使用。 可選 label 篩選器使用包含精確 key 與 value 字串的物件。 資源標籤與版本標籤是不同的。
登錄識別碼必須為 1-128 個字元,以 ASCII 字母、數字或底線開頭,且僅包含 ASCII 字母、數字、-、~、:、.、_ 或 @。 使用發現結果,而非建構識別碼。 無效的參數、不存在的資源、服務錯誤以及逾時都是錯誤,而非成功的空文件。
list_edge_registry_groups
在 xRegistry 群組集合中列出群組 ID。
| Argument | Required | Meaning |
|---|---|---|
group_type |
Yes | 群組集合名稱,例如 schemagroups。 |
呼叫 aio_list_edge_registry_groups:
{
"group_type": "schemagroups"
}
範例結果:
{
"groups": ["example-schema-group"]
}
此方法僅回傳 ID,不會回傳群組的元資料或結構。 使用含有 get_edge_registry_group 的 ID,或使用群組範圍的清單。
groups 陣列為空表示集合未回傳任何群組。 其他工具使用的雲端預設群組是選取行為,而非名為 default的字面 ID 。
get_edge_registry_group
讀取群組的中繼資料及資源集合的數量統計。
| Argument | Required | Meaning |
|---|---|---|
group_type |
Yes | 群組集合名稱。 |
group_id |
No | 精確群組 ID;省略以解析雲端預設群組。 |
呼叫 aio_get_edge_registry_group:
{
"group_type": "schemagroups"
}
結果範例(節錄):
{
"group_id": "example-schema-group",
"labels": [],
"resources_counts": {
"schemas": 2
}
}
完整結果包括 xid、epoch、建立與修改時間、可選的描述性或棄用中繼資料,以及 extensions。 擴充功能值為 base64 編碼。 數量並非文件本身;利用資源清單來發現 ID。 不存在的群組會傳回錯誤訊息。
list_edge_registry_resources
為類型化集合尋找資源參照,並可選擇性地依資源標籤進行篩選。
| Argument | Required | Meaning |
|---|---|---|
resource_kind |
Yes |
schema、thing_description 或 thing_model。 |
group_id |
No | 選擇一個群組。 |
all_groups |
No | 布林值,預設值為 false;無法與 group_id 組合使用。 |
label |
No | 與 {"key":"environment","value":"test"} 相同的精確資源標籤。 |
呼叫 aio_list_edge_registry_resources:
{
"resource_kind": "schema"
}
範例結果:
{
"resources": [
{
"group_type": "schemagroups",
"group_id": "example-schema-group",
"resource_type": "schemas",
"resource_id": "telemetry-schema"
}
]
}
這些資源參照不是版本或文件內容。 使用傳回的 resource_id 搭配 get 工具。 若要搜尋其他群組,請設定 group_id 或 all_groups;否則非預設群組中的結構不會顯示。 如果沒有相符項目,resources 陣列為空。
list_edge_registry_resource_versions
查看版本參照。 您可以依資源 ID、文件雜希或版本標籤縮小結果範圍。
| Argument | Required | Meaning |
|---|---|---|
resource_kind |
Yes |
schema、thing_description 或 thing_model。 |
group_id |
No | 選擇一個群組。 |
all_groups |
No | 布林值,預設 false 值;無法與 group_id 組合使用。 |
resource_id |
No | 精確的資源 ID。 |
document_hash |
No | 用於比對的精確文件雜湊值 |
label |
No | 精確版本標籤,含有 key 和 value。 |
呼叫 aio_list_edge_registry_resource_versions:
{
"resource_kind": "schema",
"resource_id": "telemetry-schema"
}
範例結果:
{
"versions": [
{
"group_type": "schemagroups",
"group_id": "example-schema-group",
"resource_type": "schemas",
"resource_id": "telemetry-schema",
"version_id": 1
}
]
}
將所提供的篩選條件組合起來,以縮小結果範圍。 您可以將回傳的數 version_id 值傳入 get_edge_registry_resource。 資源發現並不會取代版本發現:資源標籤不是版本標籤。 若無匹配,陣列 versions 為空且不會傳回錯誤。
get_edge_registry_resource
擷取具類型的資源的預設或指定版本,包括文件內容與版本中繼資料。
| Argument | Required | Meaning |
|---|---|---|
resource_kind |
Yes |
schema、thing_description 或 thing_model。 |
resource_id |
Yes | 來自探索功能的精確資源 ID。 |
group_id |
No | 群組 ID;若為雲端預設群組則省略。 |
version_id |
No | 未簽名整數;為資源預設版本省略。 |
呼叫 aio_get_edge_registry_resource:
{
"resource_kind": "schema",
"resource_id": "telemetry-schema"
}
結果範例(節錄):
{
"resource_kind": "schema",
"resource_id": "telemetry-schema",
"version_id": 1,
"document": "{\"type\":\"object\"}",
"document_encoding": "utf8"
}
回應包含已解析的 group_id、xid、epoch、標籤、時間戳記、is_default 格式與驗證中繼資料、文件雜湊值以及擴充功能。
document 是字串:在解讀其格式之前,請依照 document_encoding(utf8 或 base64)將其解碼。 以 UTF-8 編碼的 JSON 結構描述在工具結果中仍然是 JSON 字串。
驗證物件會回報 validated 以及可選的 reason;成功擷取並不表示格式或相容性驗證已通過。 擴充功能採用 base64 編碼。 此類型回應描述一個版本;使用通用工具處理資源層級的元資料。
get_edge_registry_generic_resource
取得 xRegistry 資源及其資源層級中繼資料,以及其預設或指定版本。 將此工具用於類型化 get 工具未涵蓋的集合類型或字串版本識別碼。
| Argument | Required | Meaning |
|---|---|---|
group_type |
Yes | xRegistry 群組集合名稱。 |
resource_type |
Yes | xRegistry 資源集合名稱。 |
resource_id |
Yes | 精確的資源 ID。 |
group_id |
No | 群組 ID;若為雲端預設群組則省略。 |
version_id |
No | 字串版本 ID,與具型別工具的整數版本 ID 不同。 |
呼叫 aio_get_edge_registry_generic_resource:
{
"group_type": "schemagroups",
"resource_type": "schemas",
"resource_id": "telemetry-schema",
"version_id": "1"
}
結果範例(節錄):
{
"resource_id": "telemetry-schema",
"meta": {
"default_version_id": "1"
},
"version": {
"version_id": "1",
"document": "{\"type\":\"object\"}",
"document_encoding": "utf8"
}
}
完整結果包含集合名稱、已解析的群組 ID、xid、versions_count、資源 meta、所選的 version及擴充功能。
meta 描述預設版本選擇、相容性及唯讀狀態;version 包含所選文件及版本中繼資料。 選擇非預設版本不會改變資源的預設值。
依照 version.document_encoding 解碼文件內容。 文件可以在通用回應中缺失,而擴充功能值則以 base64 編碼。 不存在版本會傳回錯誤,而非悄無聲息地回復預設值。
get_edge_registry_schema_from_asset
確定資產資料集所回報的訊息結構描述參考所指向的確切結構描述版本。
| Argument | Required | Meaning |
|---|---|---|
asset |
Yes | 精確的資產資源名稱。 |
dataset |
Yes | 資產的報告 status.datasets中的資料集名稱。 |
呼叫 aio_get_edge_registry_schema_from_asset:
{
"asset": "oven",
"dataset": "temperature"
}
結果範例(節錄):
{
"resource_kind": "schema",
"version_id": 1,
"document": "{\"type\":\"object\"}",
"document_encoding": "utf8"
}
工具會從資料集的訊息結構描述參考讀取 schemaName 和 schemaVersion,然後從 cloud-default 結構描述群組擷取該版本。 這個工具不會將 schemaRegistryNamespace 解讀為群組 ID。 回應具有與 get_edge_registry_resource 相同的文件、編碼及元資料語意。
即使您設定了資料集,也無法解析沒有報告參照的資產。 若缺少資產或參考,此工具會回傳錯誤。 欄位不完整或非數字版本無效。 先使用 get_asset 檢查資產的狀態。 此工具需要同時具備 Kubernetes 資產讀取權限與 Edge Registry 存取權限。
MQTT 與狀態儲存資料工具
這些工具是使用後端代理者身份,而非原始 MCP 用戶端的身份來運作。 授權呼叫者時請依此進行:後端的下游主題與金鑰授權無法取代 MCP 授權。 讀取有效載荷或數值可能會暴露應用程式資料。
mq_messages
暫時訂閱並收集 MQTT 訊息,直到達到計數上限或逾時為止。 例如,請您的代理從一個非運作中的測試主題名稱中取樣一則訊息。
| Argument | Required | Meaning |
|---|---|---|
topic |
Yes | MQTT 主題篩選器;支援 MQTT + 與 # 萬用字元。 |
timeout_ms |
No | 等待時間為無符號毫秒;預設 60000。 |
max_messages |
No | 未簽署訊息限制;預設 100,最大值 1000。 |
在抽樣開始後,使用獨立授權的 MQTT 用戶端發佈 hello world 至範例主題。 若要得到以下結果,發布時不要設定 MQTT 酬載格式指示器。 呼叫 aio_mq_messages:
{
"topic": "mcp/examples/sample",
"timeout_ms": 5000,
"max_messages": 1
}
範例結果:
{
"messages": [
{
"payload": "aGVsbG8gd29ybGQ=",
"payload_format_indicator": "Unspecified"
}
]
}
使用 UTF8 有效載荷格式指示器時,payload 是文字。 在 Unspecified的情況下,它是以 base64 編碼的位元組,即使這些位元組恰好包含可讀文字。 選填欄位包括 content_type、message_expiry_interval、response_topic、base64 correlation_data 及 user_properties。 訊息條目不包含其 MQTT 主題;若需要區分來源主題,請避免使用寬泛的萬用字元。
此工具訂閱時,QoS 最高為 1。 它會抽樣呼叫期間收到的訊息,包括任何在訂閱時送達的保留訊息;它不會查詢歷史流量。 逾時可回傳少於請求的數量,包括 {"messages":[]},且不會發生錯誤。 零計數表示不請求任何訊息。 無效篩選器、計數超過 1000,或未提交訂閱請求會傳回錯誤訊息。
這個工具不會等待或檢查訊息代理程式的訂閱確認(SUBACK)。 經紀商端的訂閱拒絕,例如授權失敗,因此可能會回傳 {"messages":[]},而不是錯誤。 如果取樣意外未回傳任何訊息,請先檢查後端的代理權限,再判斷該主題無流量。
後端需要為所選篩選條件具有訂閱權限。 廣泛的 MCP 授權允許取樣後端可訂閱的任何過濾器;當呼叫者需要更窄的存取權時,可在 MCP 政策中使用參數條件。 不要用生產流量來測試有效載荷存取。
mqtt_publish
將 JSON 物件發佈到一個 MQTT 主題。 此工具執行寫入操作,與本文其他工具不同。
| Argument | Required | Meaning |
|---|---|---|
topic |
Yes | 精確的 MQTT 主題名稱;不允許使用萬用字元。 |
payload |
Yes | JSON 物件,而不是 JSON 字串、陣列或純量。 |
在呼叫工具之前,先針對你獨特的測試主題啟動一個獨立授權的訂閱者。 呼叫 aio_mqtt_publish:
{
"topic": "mcp/examples/publish",
"payload": {
"message": "Hello from MCP"
}
}
範例結果:
{}
內建工具以 QoS 1 發佈,保留已停用、內容類型 application/json,以及 UTF-8 有效載荷格式指示器。 成功的空物件表示代理接受了發佈;這並不證明有訂閱者或下游應用程式處理了該訊息。 請另外向訂閱者確認酬載。
後端需要訊息代理程式的發佈權限,而 MCP 用戶端則需要明確的工具授權。 請參閱允許寫入工具,瞭解專屬角色和精確主題條件。 發佈失敗即為錯誤。 取消或逾時可能導致交付狀態未知;不要自動重試對後續影響非冪等的操作。
dss_get
依鍵讀取一個分散式狀態儲存值。 此工具不會建立、更新或刪除金鑰。
| Argument | Required | Meaning |
|---|---|---|
key_name |
Yes | UTF-8 金鑰名稱,或在使用 Base64. 時使用基數 64 編碼的金鑰位元組。 |
key_encoding |
No | 區分 String 大小寫(預設)或 Base64。 這控制的是金鑰本身,而非結果編碼。 |
使用獨立授權的狀態儲存用戶端,建立帶有值hello world且具有短到期時間的測試鍵mcp/examples/key。 呼叫 aio_dss_get:
{
"key_name": "mcp/examples/key"
}
範例結果:
{
"value": "aGVsbG8gd29ybGQ="
}
若要將相同的金鑰讀取為位元組,請呼叫 aio_dss_get:
{
"key_name": "bWNwL2V4YW1wbGVzL2tleQ==",
"key_encoding": "Base64"
}
結果具有相同的 value。 值永遠以 base64 編碼,無論鍵的編碼為何。 在解讀應用程式內容之前先解碼 value ;此工具不會推斷 JSON 或文字格式。
缺少鍵值與儲存的空位元組值都會產生 {"value":""};回應不會區分兩者或回傳版本元資料。 無效的 base64 會導致引數錯誤。 權限失敗以及 State Store 用戶端的 10 秒操作逾時是錯誤,而非缺少金鑰。 後端需要 State Store 讀取權才能取得 State Store 協定所需的金鑰,以及 MQTT 存取權。 完成後刪除測試金鑰。
Broker 中繼資料工具
代理程式中繼資料
查看目前的 MQTT 工作階段、訂閱、用戶端佇列狀態及保留訊息主題名稱。 例如,代理程式可以列出中斷連線的工作階段,並將其工作階段標籤對應到佇列中的訊息數量。 此工具不會讀取 MQTT 訊息酬載。
首先 啟用 broker 中繼資料存取。 後端需要具有代理伺服器的 MQTT 5 存取權限,並明確取得下列中繼資料主題的訂閱授權;對 # 的授權不包含對 $SYS 的授權。
| Query | 所需的經紀人訂閱權限 |
|---|---|
Topology |
$SYS/topology |
Sessions,無需金鑰 |
$SYS/topology 以及 $SYS/store/sessions/# |
Sessions,帶有金鑰 |
$SYS/store/sessions/<client-id> |
ClientState |
$SYS/topology,可使用 $SYS/store/client_state/# 以顯示商品列表,或使用 $SYS/store/client_state/<session-tag> 進行查詢 |
Retain |
$SYS/topology 以及 $SYS/store/retain/# |
元資料是使用後端的身分讀取的。 收集結果不會被原始呼叫者的 MQTT 主題權限過濾。 僅授予有權檢視用戶端 ID、訂閱、佇列狀態及保留主題名稱的呼叫端存取權限。
| Argument | Required | Meaning |
|---|---|---|
query |
Yes | 區分大小寫的 Topology、Sessions、ClientState 或 Retain。 |
key |
No |
frontendId:generationId:connectionKey 的確切 MQTT 用戶端 ID,或 Sessions 的 ClientState。 若為清單則省略。 |
金鑰不支援 + 或 # 萬用字元。
Topology 和 Retain 拒絕鍵。 清單會回傳 items 陣列;精確查詢會回傳 item 物件,或在沒有任何項目符合時回傳 null。
取得後端鏈數
呼叫 aio_broker_metadata:
{
"query": "Topology"
}
範例結果:
{
"chains": 4
}
chains 是後端分割區數量乘以每個分割區的工作者數。 兩個分割區,每個分割區有兩個工作者,會產生四條邏輯鏈。 問題不是分割區數或複本數。
檢查工作階段與訂閱
呼叫 aio_broker_metadata 以列出工作階段:
{
"query": "Sessions"
}
結果包含 items,每個工作階段各有一個物件。 要檢查一個工作階段,請使用唯一的用戶端 ID 連線測試 MQTT 用戶端,並以該 ID 取代 sensor-a。 呼叫 aio_broker_metadata:
{
"query": "Sessions",
"key": "sensor-a"
}
範例結果:
{
"item": {
"clientId": "sensor-a",
"sessionTag": {
"frontendId": 1,
"generationId": 0,
"connectionKey": 12345
},
"connected": true,
"expiryIntervalS": 3600,
"keepAlive": 60,
"receiveMaximum": 16,
"persistent": true,
"subscriptions": [
{
"filter": "telemetry/#",
"qos": 1,
"noLocal": false,
"retainAsPublished": false,
"retainHandling": 0
}
]
}
}
expiryIntervalS 是工作階段到期間隔(秒數);null 表示無到期時間。 斷開連線的工作階段也包含 expiresAtS,即以 Unix 秒表示的到期時間。 中斷連線後,工作階段仍可保留至到期。 每個訂閱都包含篩選條件、最大 QoS 以及訂閱選項。 空 subscriptions 陣列表示該工作階段未記錄任何訂閱。
檢查佇列中及傳輸中的訊息
呼叫 aio_broker_metadata 以列出用戶端狀態:
{
"query": "ClientState"
}
結果包含 items。 查詢時,請使用測試用戶端的 sessionTagSessions 結果,格式為 frontendId:generationId:connectionKey。 請將下方的示範金鑰替換為該標籤,而非用戶端 ID。 呼叫 aio_broker_metadata:
{
"query": "ClientState",
"key": "1:0:12345"
}
範例結果:
{
"item": {
"clientId": "sensor-a",
"frontendId": 1,
"generationId": 0,
"connectionKey": 12345,
"connected": true,
"queueDepth": 5,
"inflight": 2,
"receiveMaximum": 16,
"isPersisted": true
}
}
此工具依工作階段標籤合併所有後端鏈的狀態,並加總 queueDepth 和 inflight。
clientId 在沒有相符的工作階段項目可用時可以是 null。
receiveMaximum 限制代理程式在收到確認前所能發送的 QoS 1 訊息。 佇列數量是目前的觀測值,而非累積的流量指標。
列出保留的主題名稱
使用獨立授權的 MQTT 用戶端,在唯一測試主題上發佈保留訊息,然後呼叫 aio_broker_metadata:
{
"query": "Retain"
}
範例結果:
{
"items": [
"mcp/examples/retained"
]
}
此輸出僅列出名稱,不列出保留的有效載荷,且不支援精確主題鍵。 它還會顯示代理伺服器中的其他保留主題。 透過向同一主題發佈空的保留有效載荷,清除您的測試保留訊息。
解讀元資料結果與錯誤
空 items 陣列表示查詢成功但未找到任何條目。
{"item":null} 代表精確查詢未找到匹配。 連線失敗、訂閱被拒絕、逾時以及無效回應都是錯誤,而不是空白結果。
列表會收集來自所有後端鏈的回應。 如果預期的鏈沒有回應,工具會回傳逾時錯誤,而非部分清單。 結果不會有順序,也不會是跨鏈或分開呼叫的同步快照。 它們沒有提供歷史或連續事件串流。
如果工具看不到,請檢查工具可用性和 MCP 授權。 如果訂閱被拒絕,請檢查後端的 broker 對所需 $SYS 主題的權限。 不要把 MQTT 權限授予原始呼叫者以修正後端拒絕。
排除工具呼叫問題
工具探索與成功呼叫是分開的檢查。 列出的工具仍可能因特定參數而被拒絕,或因下游服務無法使用而失敗。 無效的參數和下游失敗可能會以 JSON-RPC 錯誤或工具錯誤內容的形式出現,視失敗情況和用戶端而定。
若找不到工具,請檢查呼叫者的角色、連線的政策以及後端設定。 對於資源讀取,請檢查命名空間範圍及後端 Kubernetes 權限。 對於 MQTT、State Store 和 Edge Registry 呼叫,請檢查代理程式連線,以及後端的下游存取權限。 不要將錯誤視為有效的空結果,也不要繞過 MCP 授權來處理該錯誤。
有關連線、驗證及逾時診斷,請參閱「 MCP 疑難排解」。