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 和服務匯流排，請造訪下列連結：