Pub/sub API reference

Detailed documentation on the pub/sub API

Publish a message to a given topic

This endpoint lets you publish data to multiple consumers who are listening on a topic. Dapr guarantees at least once semantics for this endpoint.

HTTP 请求

POST http://localhost:<daprPort>/v1.0/publish/<pubsubname>/<topic>[?<metadata>]

HTTP 响应码

代码说明
204Message delivered
403Message forbidden by access controls
404No pubsub name or topic given
500Delivery failed

URL 参数

参数说明
daprPortdapr 端口。
pubsubnamethe name of pubsub component
topicthe name of the topic
metadataquery parameters for metadata as described below

注意:所有的 URL 参数都是大小写敏感的。

curl -X POST http://localhost:3500/v1.0/publish/pubsubName/deathStarStatus \
  -H "Content-Type: application/json" \
 -d '{
       "status": "completed"
     }'

Headers

The Content-Type header tells Dapr which content type your data adheres to when constructing a CloudEvent envelope. The value of the Content-Type header populates the datacontenttype field in the CloudEvent. Unless specified, Dapr assumes text/plain. If your content type is JSON, use a Content-Type header with the value of application/json.

If you want to send your own custom CloundEvent, use the application/cloudevents+json value for the Content-Type header.

元数据(Metadata)

Metadata can be sent via query parameters in the request’s URL. It must be prefixed with metadata. as shown below.

参数说明
metadata.ttlInSecondsthe number of seconds for the message to expire as described here
metadata.rawPayloadboolean to determine if Dapr should publish the event without wrapping it as CloudEvent as described here

Additional metadata parameters are available based on each pubsub component.

Optional Application (User Code) Routes

Provide a route for Dapr to discover topic subscriptions

Dapr will invoke the following endpoint on user code to discover topic subscriptions:

HTTP 请求

GET http://localhost:<appPort>/dapr/subscribe

URL 参数

参数说明
appPort应用程序端口

HTTP Response body

A json encoded array of strings.

You can run Kafka locally using this Docker image. To run without Docker, see the getting started guide here.

[
  {
    "pubsubname": "pubsub",
    "topic": "newOrder",
    "route": "/orders",
    "metadata": {
      "rawPayload": "true",
    }
  }
]

Note, all subscription parameters are case-sensitive.

元数据(Metadata)

Optionally, metadata can be sent via the request body.

参数说明
rawPayloadboolean to subscribe to events that do not comply with CloudEvent specification, as described here

Provide route(s) for Dapr to deliver topic events

In order to deliver topic events, a POST call will be made to user code with the route specified in the subscription response.

The following example illustrates this point, considering a subscription for topic newOrder with route orders on port 3000: POST http://localhost:3000/orders

HTTP 请求

POST http://localhost:<appPort>/<path>

注意:所有的 URL 参数都是大小写敏感的。

URL 参数

参数说明
appPort应用程序端口
pathroute path from the subscription configuration

Expected HTTP Response

An HTTP 2xx response denotes successful processing of message. For richer response handling, a JSON encoded payload body with the processing status can be sent:

{
  "status": "<status>"
}
状态说明
SUCCESSmessage is processed successfully
RETRYmessage to be retried by Dapr
DROPwarning is logged and message is dropped
Otherserror, message to be retried by Dapr

Dapr assumes a JSON encoded payload response without status field or an empty payload responses with HTTP 2xx, as SUCCESS.

The HTTP response might be different from HTTP 2xx, the following are Dapr’s behavior in different HTTP statuses:

HTTP Status说明
2xxmessage is processed as per status in payload (SUCCESS if empty; ignored if invalid payload).
404error is logged and message is dropped
otherwarning is logged and message to be retried

Message envelope

Dapr Pub/Sub adheres to version 1.0 of Cloud Events.

相关链接