傳送服務匯流排訊息

適用於:開發人員 |基本 |標準 |保險費

原則會 send-service-bus-message 將訊息傳送至 Azure 服務匯流排佇列或主題。 你可以選擇性地將 API 請求轉發給後端服務。

備註

備註

請依照原則陳述式中提供的順序,來設定原則的元素和子元素。 深入了解如何設定或編輯 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>

如需了解有關政策的更多資訊,請參閱: