共用方式為


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