Trigger output binding

  • Article

Availability

Important

This feature is available in the Premium and Developer tiers of API Management.

The invoke-dapr-binding policy instructs API Management gateway to trigger an outbound Dapr binding. The policy accomplishes that by making an HTTP POST request to http://localhost:3500/v1.0/bindings/{{bind-name}}, replacing the template parameter and adding content specified in the policy statement.

The policy assumes that Dapr runtime is running in a sidecar container in the same pod as the gateway. Dapr runtime is responsible for invoking the external resource represented by the binding. Learn more about Dapr integration with API Management.

Note

Set a policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Policy statement

<invoke-dapr-binding name="bind-name" operation="op-name" ignore-error="false | true" response-variable-name="resp-var-name" timeout="in seconds" template="Liquid" content-type="application/json">
    <metadata>
        <item key="item-name"><!-- item-value --></item>
    </metadata>
    <data>
        <!-- message content -->
    </data>
</invoke-dapr-binding>

Attributes

Attribute Description Required Default
name Target binding name. Must match the name of the bindings defined in Dapr. Policy expressions are allowed. Yes N/A
operation Target operation name (binding specific). Maps to the operation property in Dapr. Policy expressions aren't allowed. No None
ignore-error If set to true instructs the policy not to trigger "on-error" section upon receiving error from Dapr runtime. Policy expressions aren't allowed. No false
response-variable-name Name of the Variables collection entry to use for storing response from Dapr runtime. Policy expressions aren't allowed. No None
timeout Time (in seconds) to wait for Dapr runtime to respond. Can range from 1 to 240 seconds. Policy expressions are allowed. No 5
template Templating engine to use for transforming the message content. "Liquid" is the only supported value. No None
content-type Type of the message content. "application/json" is the only supported value. No None

Elements

Element Description Required
metadata Binding specific metadata in the form of key/value pairs. Maps to the metadata property in Dapr. No
data Content of the message. Maps to the data property in Dapr. Policy expressions are allowed. No

Usage

Usage notes

Dapr support must be enabled in the self-hosted gateway.

Example

The following example demonstrates triggering of outbound binding named "external-systems" with operation named "create", metadata consisting of two key/value items named "source" and "client-ip", and the body coming from the original request. Response received from the Dapr runtime is captured in the "bind-response" entry of the Variables collection in the context object.

If Dapr runtime fails for some reason and responds with an error, the "on-error" section is triggered and response received from the Dapr runtime is returned to the caller verbatim. Otherwise, default 200 OK response is returned.

The "backend" section is empty and the request is not forwarded to the backend.

<policies>
     <inbound>
        <base />
        <invoke-dapr-binding
                      name="external-system"
                      operation="create"
                      response-variable-name="bind-response">
            <metadata>
                <item key="source">api-management</item>
                <item key="client-ip">@(context.Request.IpAddress )</item>
            </metadata>
            <data>
                @(context.Request.Body.As<string>() )
            </data>
        </invoke-dapr-binding>
    </inbound>
    <backend>
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
        <return-response response-variable-name="bind-response" />
    </on-error>
</policies>

Next steps

For more information about working with policies, see: