Microsoft Azure 服務匯流排中的 AMQP 1.0：要求/回應架構作業
本文定義 Microsoft Azure 服務匯流排要求/回應架構作業的清單。 這項資訊是根據 AMQP 管理版本 1.0 工作草稿。
如需詳細的有線等級 AMQP 1.0 通訊協定指南，說明服務匯流排如何實作和建置 OASIS AMQP 技術規格，請參閱 Azure 服務匯流排和事件中樞的 AMQP 1.0 通訊協定指南。
概念
ServiceBusReceivedMessage / ServiceBusMessage
代表服務匯流排中對應至 AMQP 訊息的訊息。 此對應會在服務匯流排 AMQP 通訊協定指南中定義。
附加至實體管理節點
這份文件中所述的所有作業會遵循要求/回應模式、限定範圍至實體，並需要附加至實體管理節點。
建立傳送要求的連結
建立傳送要求的管理節點連結。
requestLink = session.attach(
role: SENDER,
target: { address: "<entity address>/$management" },
source: { address: ""<my request link unique address>" }
)
建立接收回應的連結
建立連結，以便接收來自管理節點的回應。
responseLink = session.attach(
role: RECEIVER,
source: { address: "<entity address>/$management" }
target: { address: "<my response link unique address>" }
)
傳輸要求訊息
傳輸要求訊息。
針對支援交易的作業，可以選擇性地新增交易狀態。
requestLink.sendTransfer(
Message(
properties: {
message-id: <request id>,
reply-to: "<my response link unique address>"
},
application-properties: {
"operation" -> "<operation>",
}
),
[Optional] State = transactional-state: {
txn-id: <txn-id>
}
)
接收回應訊息
從回應連結接收回應訊息。
responseMessage = responseLink.receiveTransfer()
回應訊息的格式如下：
Message(
properties: {
correlation-id: <request id>
},
application-properties: {
"statusCode" -> <status code>,
"statusDescription" -> <status description>,
},
)
服務匯流排實體位址
必須處理服務匯流排實體，如下所示︰
| 實體類型 | 位址 | 範例 |
|---|---|---|
| queue | <queue_name> |
“myQueue”“site1/myQueue” |
| 主題 | <topic_name> |
“myTopic”“site2/page1/myQueue” |
| 訂用帳戶 | <topic_name>/Subscriptions/<subscription_name> |
“myTopic/Subscriptions/MySub” |
訊息作業
訊息更新鎖定
藉由佇列或訂用帳戶上設定的鎖定持續時間來延長訊息的鎖定。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:renew-lock |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
lock-tokens |
UUID 的陣列 | Yes | 要更新的訊息鎖定權杖。 |
注意
此處的鎖定權杖是指所接收 AMQP 訊息上的 delivery-tag 屬性。 如果您收到延遲的訊息且想要更新其鎖定，請在訊息上使用屬性 lock-token，而非 delivery-tag。
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗。 |
| statusDescription | string | No | 狀態的描述。 |
回應訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 到期日 | 時間戳記的陣列 | Yes | 對應到要求鎖定權杖的訊息鎖定權杖新期限。 |
查看訊息
查看訊息而不用鎖定。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:peek-message |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
from-sequence-number |
long | Yes | 要開始查看的序號。 |
message-count |
int | Yes | 要查看的訊息數目上限。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 有多個訊息 204︰沒有內容 – 沒有其他訊息 |
| statusDescription | string | No | 狀態的描述。 |
回應訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| messages | 對應的清單 | Yes | 當中每個對應都代表一則訊息的訊息清單。 |
代表訊息的對應必須包含下列項目：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| message | 位元組的陣列 | Yes | AMQP 1.0 連線編碼訊息。 |
排程訊息
排程訊息。 此作業支援交易。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:schedule-message |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| messages | 對應的清單 | Yes | 當中每個對應都代表一則訊息的訊息清單。 |
代表訊息的對應必須包含下列項目：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| message-id | string | Yes | amqpMessage.Properties.MessageId 為字串 |
| session-id | string | No | amqpMessage.Properties.GroupId as string |
| partition-key | string | No | amqpMessage.MessageAnnotations.”x-opt-partition-key" |
| via-partition-key | string | No | amqpMessage.MessageAnnotations."x-opt-via-partition-key" |
| message | 位元組的陣列 | Yes | AMQP 1.0 連線編碼訊息。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗。 |
| statusDescription | string | No | 狀態的描述。 |
回應訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| sequence-numbers | 長整數的陣列 | Yes | 排定訊息的序號。 序號用來取消。 |
取消排定的訊息
取消排定的訊息。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:cancel-scheduled-message |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| sequence-numbers | 長整數的陣列 | Yes | 要取消之排程訊息的序號。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗。 |
| statusDescription | string | No | 狀態的描述。 |
工作階段作業
工作階段更新鎖定
藉由佇列或訂用帳戶上設定的鎖定持續時間來延長訊息的鎖定。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:renew-session-lock |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| session-id | string | Yes | 工作階段識別碼。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 有多個訊息 204︰沒有內容 – 沒有其他訊息 |
| statusDescription | string | No | 狀態的描述。 |
回應訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 到期 | timestamp | Yes | 新的到期日。 |
查看工作階段訊息
查看工作階段訊息而不用鎖定。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:peek-message |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| from-sequence-number | long | Yes | 要開始查看的序號。 |
| message-count | int | Yes | 要查看的訊息數目上限。 |
| session-id | string | Yes | 工作階段識別碼。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 有多個訊息 204︰沒有內容 – 沒有其他訊息 |
| statusDescription | string | No | 狀態的描述。 |
回應訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| messages | 對應的清單 | Yes | 當中每個對應都代表一則訊息的訊息清單。 |
代表訊息的對應必須包含下列項目：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| message | 位元組的陣列 | Yes | AMQP 1.0 連線編碼訊息。 |
設定工作階段狀態
設定工作階段的狀態。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:set-session-state |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| session-id | string | Yes | 工作階段識別碼。 |
| session-state | 位元組的陣列 | Yes | 不透明的二進位資料。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗 |
| statusDescription | string | No | 狀態的描述。 |
取得工作階段狀態
取得工作階段的狀態。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:get-session-state |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| session-id | string | Yes | 工作階段識別碼。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗 |
| statusDescription | string | No | 狀態的描述。 |
回應訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| session-state | 位元組的陣列 | Yes | 不透明的二進位資料。 |
列舉工作階段
列舉訊息實體上的工作階段。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:get-message-sessions |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| last-updated-time | timestamp | Yes | 篩選以在指定時間之後只包括更新的工作階段。 |
| skip | int | Yes | 略過工作階段數。 |
| 熱門 | int | Yes | 工作階段數上限。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 有多個訊息 204︰沒有內容 – 沒有其他訊息 |
| statusDescription | string | No | 狀態的描述。 |
回應訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| skip | int | Yes | 如果狀態碼為 200 所略過的工作階段數。 |
| sessions-ids | 字串陣列 | Yes | 如果狀態碼為 200 的工作階段識別碼陣列。 |
規則作業
新增規則
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:add-rule |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| rule-name | string | Yes | 規則名稱，不包括訂用帳戶和主題名稱。 |
| rule-description | map | Yes | 如下一節中指定的規則描述。 |
rule-description 對應必須包含下列項目，當中 sql-filter 和 correlation-filter 為互斥：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| sql-filter | map | Yes | sql-filter，如下一節中所指定。 |
| correlation-filter | map | Yes | correlation-filter，如下一節中所指定。 |
| sql-rule-action | map | Yes | sql-rule-action，如下一節中所指定。 |
sql-filter 對應必須包含下列項目：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| expression | string | Yes | Sql 篩選運算式。 |
correlation-filter 對應必須至少包含下列項目之一：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| correlation-id | string | No | |
| message-id | string | No | |
| 打給 | string | No | |
| reply-to | string | No | |
| label | string | No | |
| session-id | string | No | |
| reply-to-session-id | string | No | |
| Content-Type | string | No | |
| 內容 | map | No | 對應至服務匯流排 ServiceBusMessage.Properties |
sql-rule-action 對應必須包含下列項目：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| expression | string | Yes | Sql 動作運算式。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗 |
| statusDescription | string | No | 狀態的描述。 |
移除規則
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:remove-rule |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| rule-name | string | Yes | 規則名稱，不包括訂用帳戶和主題名稱。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗 |
| statusDescription | string | No | 狀態的描述。 |
取得規則
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:enumerate-rules |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 熱門 | int | Yes | 頁面中要提取的規則數目。 |
| skip | int | Yes | 要略過的規則數目。 定義規則清單中的起始索引 (+ 1)。 |
回應
回應訊息包含下列屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗 |
| 規則 | 對應的清單 | Yes | 規則清單。 每個規則都是以對應表示。 |
清單中的每個對應項目都包含下列屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| rule-description | 描述的物件 | Yes | com.microsoft:rule-description 以及 AMQP 描述代碼 0x0000013700000004 |
com.microsoft.rule-description 本身是描述的清單。 它具有下列屬性：
| 索引 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 0 | 描述的清單 | Yes | filter，如下表中所指定。 |
| 1 | 描述的清單 | Yes | ruleAction，如本節稍後所指定。 |
| 2 | string | Yes | 規則的名稱。 |
| 3 | timestamp | Yes | 時間戳記。 |
filter 可以是下列類型之一：
| 描述項名稱 | 描述項代碼 | 值 |
|---|---|---|
com.microsoft:sql-filter:list |
0x000001370000006 | SQL 篩選 |
com.microsoft:correlation-filter:list |
0x000001370000009 | 相互關聯篩選 |
com.microsoft:true-filter:list |
0x000001370000007 | 表示 1=1 的 True 篩選 |
com.microsoft:false-filter:list |
0x000001370000008 | 表示 1=0 的 False 篩選 |
com.microsoft:sql-filter:list 是描述的清單，其中包括：
| 索引 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 0 | string | Yes | Sql 篩選運算式 |
| 1 | int | Yes | 一律 20。 此整數是 sql 篩選條件的相容性層級。 其指出 sql 篩選條件的語法版本。 |
com.microsoft:correlation-filter:list 是描述的清單，其中包括：
| 索引 (若存在) | 值類型 | 值內容 |
|---|---|---|
| 0 | string | 相互關聯 ID |
| 1 | 字串 | 訊息 ID |
| 2 | string | 至 |
| 3 | string | 回覆 |
| 4 | string | 標籤 |
| 5 | string | 工作階段識別碼 |
| 6 | string | 回覆至工作階段識別碼 |
| 7 | string | 內容類型 |
| 8 | 地圖 | 應用程式定義屬性的對應 |
ruleAction 可以是下列類型之一：
| 描述項名稱 | 描述項代碼 | 值 |
|---|---|---|
com.microsoft:empty-rule-action:list |
0x0000013700000005 | 空白規則動作 - 沒有規則動作 |
com.microsoft:sql-rule-action:list |
0x0000013700000006 | SQL 規則動作 |
com.microsoft:sql-rule-action:list 是描述的清單，具有兩個元素。
| 索引 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 0 | string | Yes | SQL 規則動作的運算式 |
| 1 | int | Yes | 一律 20。 此整數是 sql 篩選條件的相容性層級。 其指出 sql 篩選條件的語法版本。 |
延遲的訊息作業
依照序號接收
依序號接收延遲的訊息。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:receive-by-sequence-number |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| sequence-numbers | 長整數的陣列 | Yes | 序號。 |
| receiver-settle-mode | ubyte | Yes | AMQP 核心 1.0 版中所指定的「收件者支付」模式。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗 |
| statusDescription | string | No | 狀態的描述。 |
回應訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| messages | 對應的清單 | Yes | 當中每個對應都代表一則訊息的訊息清單。 |
代表訊息的對應必須包含下列項目：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| lock-token | uuid | Yes | 如果 receiver-settle-mode 為 1 則鎖定權杖。 |
| message | 位元組的陣列 | Yes | AMQP 1.0 連線編碼訊息。 |
更新配置狀態
更新延遲訊息的配置狀態。 此作業支援交易。
要求
要求訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| 作業 | string | Yes | com.microsoft:update-disposition |
com.microsoft:server-timeout |
uint | No | 作業伺服器逾時以毫秒為單位。 |
要求訊息本文必須由包含對應與下列項目的 amqp-value 區段所組成：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| disposition-status | string | Yes | 已完成 放棄 暫止 |
| lock-tokens | UUID 的陣列 | Yes | 要更新配置狀態的訊息鎖定權杖。 |
| deadletter-reason | string | No | 如果配置狀態設定為 暫停 則可能會設定。 |
| deadletter-description | string | No | 如果配置狀態設定為 暫停 則可能會設定。 |
| properties-to-modify | map | No | 要修改的服務匯流排代理訊息屬性清單。 |
回應
回應訊息必須包含下列應用程式屬性：
| 機碼 | 值類型 | 必要 | 值內容 |
|---|---|---|---|
| statusCode | int | Yes | HTTP 回應碼 [RFC2616] 200：確定 – 成功，否則失敗 |
| statusDescription | string | No | 狀態的描述。 |
下一步
若要深入了解 AMQP 和服務匯流排，請造訪下列連結：