適用於:開發人員 |基本 |標準 |保險費
原則會 send-service-bus-message 將訊息傳送至 Azure 服務匯流排佇列或主題。 你可以選擇性地將 API 請求轉發給後端服務。
備註
- 如需將訊息傳送至 Azure 服務匯流排的背景和必要條件,請參閱 如何從 Azure API 管理 將訊息傳送至 Azure 服務匯流排。
備註
請依照原則陳述式中提供的順序,來設定原則的元素和子元素。 深入了解如何設定或編輯 APIM 原則。
政策聲明
<send-service-bus-message
queue-name="service bus queue"
topic-name="service bus topic"
namespace="FQDN of service bus namespace"
client-id="ID of user-assigned managed identity"
message-id="message ID"
session-id="session ID"
time-to-live="message time to live"
response-variable-name="context variable name"
ignore-error="false">
<message-properties>
<message-property name="property-name">property-value</message-property>
<!-- if there are multiple properties, then add additional message-property elements -->
</message-properties>
<payload>"message content"</payload>
</send-service-bus-message>
Attributes
| Attribute | Description | 為必填項目 | 預設 |
|---|---|---|---|
queue-name |
指定要將訊息傳送至的服務匯流排佇列名稱。 允許原則運算式和具名值。
queue-name必須指定 或 topic-name 。 |
否 | N/A |
topic-name |
指定要傳送訊息的服務匯流排主題名稱。 允許原則運算式和具名值。
queue-name必須指定 或 topic-name 。 |
否 | N/A |
namespace |
指定服務匯流排命名空間的完整網域名稱。 允許原則運算式和具名值。 | 否 | N/A |
client-id |
指定使用者指派受控識別的用戶端識別碼,以向服務匯流排進行驗證。 身分識別必須指派 Azure 服務匯流排資料傳送者角色。 允許原則運算式和具名值。 如果你沒有指定這個屬性,就會使用系統指定的身份。 | 否 | N/A |
message-id |
訊息識別碼。 必須是有效的 GUID。 允許使用原則運算式。 若省略,API 管理會產生一個 GUID。 | 否 | 生成 GUID |
session-id |
服務匯流排 會話識別碼用於分組相關訊息。 必須是有效的 GUID。 允許使用原則運算式。 | 否 | N/A |
time-to-live |
訊息在處理期限前還能持續多久。 例如使用TimeSpan值 00:10:00。 |
否 | N/A |
response-variable-name |
一個上下文變數名稱,該變數接收關於 服務匯流排 發送操作的資訊。 | 否 | N/A |
ignore-error |
服務匯流排 傳送失敗是否應該允許政策執行繼續。
true = 繼續; false = 呼叫正常錯誤處理。 |
否 | false |
備註
當你指定 response-variable-name時,API Management 會將 服務匯流排 send 操作的資訊儲存在該上下文變數中。 成功時,包含 MessageId、 SessionId和 TimeToLive。 在忽略傳送失敗時,它包含 Error.Reason 和 Error.Message。
Elements
| 元素 | Description | 為必填項目 |
|---|---|---|
payload |
指定要傳送至服務匯流排的訊息承載。 允許原則運算式和具名值。 | Yes |
message-properties |
子元素的 message-property 集合,可指定要與訊息承載一起傳遞的中繼資料。 每個都 message-property 由名稱值對組成。 允許原則運算式和具名值。 |
否 |
Usage
使用量注意事項
- 您必須預先建立接收訊息的 Azure 服務匯流排佇列或主題。
- 你可以在每個政策定義中多次使用此政策。
- 如果你省略
message-id了 ,API 管理會產生一個 GUID。 - 配置
message-id與session-id值必須是有效的 GUID。 - 當 服務匯流排 實體需要 session 時使用
session-id。 -
time-to-live使用TimeSpan如 的值。00:10:00 -
ignore-error適用於發送失敗。 訊息設定無效,如 GUID 或 TTL 無效,仍會導致政策失敗。
範例
將訊息傳送至服務匯流排佇列
在此範例中,包含請求主體的訊息會被送入訂單佇列。 請求 ID 會變成訊息 ID,訊息在 10 分鐘後失效,發送資訊則儲存在 serviceBusResult。 傳送失敗會觸發 API 管理錯誤處理。 API 管理 執行個體會使用使用者指派的身分識別進行存取。 然後,請求會轉送至後端服務。
<policies>
<inbound>
<send-service-bus-message
queue-name="orders"
namespace="contoso-messaging.servicebus.windows.net"
message-id="@(context.RequestId.ToString())"
time-to-live="00:10:00"
response-variable-name="serviceBusResult"
ignore-error="false">
<payload>
@(context.Request.Body.As<string>(preserveContent: true))
</payload>
</send-service-bus-message>
</inbound>
<backend>
<forward-request timeout="60"/>
</backend>
</policies>
將訊息傳送至服務匯流排主題
在這個例子中,你傳送包含請求內容的訊息給服務總線主題。 API 管理 實例會使用系統指派的身分識別進行存取。 接著,你將請求轉發給後端服務。
<policies>
<inbound>
<send-service-bus-message topic-name="orders" namespace="my-service-bus.servicebus.windows.net">
<payload>@(context.Request.Body.As<string>(preserveContent: true))</payload>
</send-service-bus-message>
</inbound>
<backend>
<forward-request timeout="60"/>
</backend>
</policies>
傳送訊息和中繼資料
在這個例子中,你將包含請求內容的訊息傳送給服務匯流排主題,並設定訊息屬性以傳送元資料與有效載荷一同。 API 管理 實例會使用系統指派的身分識別進行存取。 接著,你將請求轉發給後端服務。
<policies>
<inbound>
<send-service-bus-message topic-name="orders" namespace="my-service-bus.servicebus.windows.net">
<message-properties>
<message-property name="Customer">Contoso</message-property>
</message-properties>
<payload>@(context.Request.Body.As<string>(preserveContent: true))</payload>
</send-service-bus-message>
</inbound>
<backend>
<forward-request timeout="60"/>
</backend>
</policies>
發送訊息並立即返回
在這個例子中,你傳送包含請求內容的訊息給服務總線主題。 API 管理 實例會使用系統指派的身分識別進行存取。 接著,你會立即回傳 201 回應狀態碼給來電者。
<policies>
<inbound>
<send-service-bus-message topic-name="orders" namespace="my-service-bus.servicebus.windows.net">
<payload>@(context.Request.Body.As<string>(preserveContent: true))</payload>
</send-service-bus-message>
<return-response>
<set-status code="201" reason="Created!" />
</return-response>
</inbound>
</policies>
相關原則
相關內容
如需了解有關政策的更多資訊,請參閱: