HTTP binding 规范

HTTP binding 组件的详细文档

备选方案

服务调用 API 允许调用非 Dapr HTTP 端点，是推荐的方式。阅读 “如何操作：使用 HTTP 调用非 Dapr 端点” 了解更多信息。

配置 Dapr 组件

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.http
  version: v1
  metadata:
    - name: url
      value: "http://something.com"
    #- name: maxResponseBodySize
    #  value: "100Mi" # 可选，从响应中读取的最大数据量
    #- name: MTLSRootCA
    #  value: "/Users/somepath/root.pem" # 可选，根 CA 路径或 PEM 编码字符串
    #- name: MTLSClientCert
    #  value: "/Users/somepath/client.pem" # 可选，客户端证书路径或 PEM 编码字符串
    #- name: MTLSClientKey
    #  value: "/Users/somepath/client.key" # 可选，客户端密钥路径或 PEM 编码字符串
    #- name: MTLSRenegotiation
    #  value: "RenegotiateOnceAsClient" # 可选，可选值之一：RenegotiateNever、RenegotiateOnceAsClient、RenegotiateFreelyAsClient
    #- name: securityToken # 可选，<作为头部包含在 HTTP 请求中的令牌>
    #  secretKeyRef:
    #    name: mysecret
    #    key: "mytoken"
    #- name: securityTokenHeader
    #  value: "Authorization: Bearer" # 可选，<安全令牌的头部名称>
    #- name: errorIfNot2XX
    #  value: "false" # 可选

规范元数据字段

字段	必填	Binding 支持	详情	示例
`url`	Y	输出	要调用的 HTTP 端点的基础 URL	`http://host:port/path`、`http://myservice:8000/customers`
`maxResponseBodySize`	N	输出	要读取的响应的最大长度。整数被解释为字节；为方便起见，可以添加 `Ki, Mi, Gi`（SI）或 `k	M
`MTLSRootCA`	N	输出	根 CA 证书路径或 PEM 编码字符串
`MTLSClientCert`	N	输出	客户端证书路径或 PEM 编码字符串
`MTLSClientKey`	N	输出	客户端私钥路径或 PEM 编码字符串
`MTLSRenegotiation`	N	输出	要使用的 mTLS 重新协商类型	`RenegotiateOnceAsClient`
`securityToken`	N	输出	要作为头部添加到 HTTP 请求的令牌值。与 `securityTokenHeader` 一起使用
`securityTokenHeader`	N	输出	HTTP 请求上 `securityToken` 的头部名称
`errorIfNot2XX`	N	输出	当响应不在 2xx 范围内时是否应抛出 binding 错误。默认为 `true`

MTLSRootCA、MTLSClientCert 和 MTLSClientKey 的值可以通过三种方式提供：

secret store 引用：

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.http
  version: v1
  metadata:
  - name: url
    value: http://something.com
  - name: MTLSRootCA
    secretKeyRef:
      name: mysecret
      key: myrootca
auth:
  secretStore: <NAME_OF_SECRET_STORE_COMPONENT>

文件路径：可以将文件的绝对路径作为字段的值提供。
PEM 编码字符串：也可以将 PEM 编码的字符串作为字段的值提供。

注意

元数据字段 MTLSRootCA、MTLSClientCert 和 MTLSClientKey 用于配置 mTLS 认证。要使用 mTLS 认证，必须提供所有三个字段。有关更多详细信息，请参阅 mTLS。您也可以仅提供 MTLSRootCA，以启用由自定义 CA 签名的证书的 HTTPS 连接。有关更多详细信息，请参阅 HTTPS 部分。

Binding 支持

此组件支持 输出 binding，支持以下 HTTP 方法/动词：

create ：出于向后兼容性考虑，被视为 post
get ：读取数据/记录
head ：与 get 相同，但服务器不返回响应体
post ：通常用于创建记录或发送命令
put ：更新数据/记录
patch ：有时用于更新记录的字段子集
delete ：删除数据/记录
options ：请求有关可用通信选项的信息（不常用）
trace ：用于调用远程的应用层请求消息回送（不常用）

请求

操作元数据字段

上述所有操作都支持以下元数据字段

字段	必填	详情	示例
`path`	N	要附加到基础 URL 的路径。用于访问特定的 URI。	`"/1234"`、`"/search?lastName=Jones"`
首字母大写的字段	N	任何首字母大写的字段都将作为请求头部发送	`"Content-Type"`、`"Accept"`

检索数据

要从 HTTP 端点检索数据，请使用 GET 方法调用 HTTP binding 并使用以下 JSON 正文：

{
  "operation": "get"
}

可以选择指定路径以与资源 URI 交互：

{
  "operation": "get",
  "metadata": {
    "path": "/things/1234"
  }
}

响应

响应正文包含 HTTP 端点返回的数据。data 字段包含 HTTP 响应正文，作为字节切片（通过 curl 进行 Base64 编码）。metadata 字段包含：

字段	必填	详情	示例
`statusCode`	Y	HTTP 状态码	`200`、`404`、`503`
`status`	Y	状态描述	`"200 OK"`、`"201 Created"`
首字母大写的字段	N	任何首字母大写的字段都将作为请求头部发送	`"Content-Type"`

示例

请求基础 URL

curl -d "{ \"operation\": \"get\" }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get" }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

请求特定路径

curl -d "{ \"operation\": \"get\", \"metadata\": { \"path\": \"/things/1234\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

发送和更新数据

要向 HTTP 端点发送数据，请使用 POST、PUT 或 PATCH 方法调用 HTTP binding 并使用以下 JSON 正文：

注意

任何以大写字母开头的元数据字段都将作为请求头部传递。例如，默认的内容类型为 application/json; charset=utf-8。可以通过设置 Content-Type 元数据字段来覆盖。

{
  "operation": "post",
  "data": "content (default is JSON)",
  "metadata": {
    "path": "/things",
    "Content-Type": "application/json; charset=utf-8"
  }
}

示例

发布新记录

curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \
      http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

使用 HTTPS

通过配置 Dapr 边车以信任服务器的 SSL 证书，HTTP binding 也可以与 HTTPS 端点一起使用。

将 binding URL 更新为使用 https 而不是 http。
如果需要添加自定义 TLS 证书，请参阅如何操作：在 Dapr 边车中安装证书，在边车中安装 TLS 证书。

示例

更新 binding 组件

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
  namespace: <NAMESPACE>
spec:
  type: bindings.http
  version: v1
  metadata:
  - name: url
    value: https://my-secured-website.com # 使用 HTTPS

在边车中安装 TLS 证书

当边车未在容器内运行时，TLS 证书可以直接安装在主机操作系统上。

以下是边车作为容器运行时的示例。SSL 证书位于主机上的 /tmp/ssl/cert.pem。

version: '3'
services:
  my-app:
    # ...
  dapr-sidecar:
    image: "daprio/daprd:1.8.0"
    command: [
      "./daprd",
     "-app-id", "myapp",
     "-app-port", "3000",
     ]
    volumes:
        - "./components/:/components"
        - "/tmp/ssl/:/certificates" # 将证书文件夹挂载到边车容器的 /certificates
    environment:
      - "SSL_CERT_DIR=/certificates" # 将环境变量设置为证书文件夹的路径
    depends_on:
      - my-app

边车可以从各种源读取 TLS 证书。有关更多信息，请参阅如何操作：将 Pod 卷挂载到 Dapr 边车。在此示例中，我们将 TLS 证书存储为 Kubernetes secret。

kubectl create secret generic myapp-cert --from-file /tmp/ssl/cert.pem

下面的 YAML 是 Kubernetes 部署的示例，该部署将上述 secret 挂载到边车，并设置 SSL_CERT_DIR 以安装证书。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: default
  labels:
    app: myapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
      annotations:
        dapr.io/enabled: "true"
        dapr.io/app-id: "myapp"
        dapr.io/app-port: "8000"
        dapr.io/volume-mounts: "cert-vol:/certificates" # 将证书文件夹挂载到边车容器的 /certificates
        dapr.io/env: "SSL_CERT_DIR=/certificates" # 将环境变量设置为证书文件夹的路径
    spec:
      volumes:
        - name: cert-vol
          secret:
            secretName: myapp-cert
...

安全地调用 binding

curl -d "{ \"operation\": \"get\" }" \
      https://localhost:<dapr-port>/v1.0/bindings/<binding-name>

curl -d '{ "operation": "get" }' \
      https://localhost:<dapr-port>/v1.0/bindings/<binding-name>

注意

还可以使用 MTLSRootCA 元数据选项配置 HTTPS binding 支持。这将把指定的证书添加到 binding 的受信任证书列表中。两种方法没有特定的偏好。虽然 MTLSRootCA 选项易于使用且不需要对边车进行任何更改，但它仅接受一个证书。如果您需要信任多个证书，则需要按照上述步骤在边车中安装它们。

使用 mTLS 或在 HTTPS 的同时启用客户端 TLS 认证

您可以通过在 binding 组件中提供 MTLSRootCA、MTLSClientCert 和 MTLSClientKey 元数据字段，将 HTTP binding 配置为使用 mTLS 或客户端 TLS 认证以及 HTTPS。

这些字段可以作为文件路径或 pem 编码字符串传递：

如果提供文件路径，则读取文件并使用其内容。
如果提供 PEM 编码的字符串，则按原样使用该字符串。

配置这些字段后，Dapr 边车使用提供的证书在 TLS 握手过程中向服务器验证自身。

如果远程服务器强制执行 TLS 重新协商，您还需要设置元数据字段 MTLSRenegotiation。此字段接受以下选项之一：

RenegotiateNever
RenegotiateOnceAsClient
RenegotiateFreelyAsClient

有关更多详细信息，请参阅 Go RenegotiationSupport 文档。

当配置 HTTP binding 进行通信的服务器需要 mTLS 或客户端 TLS 认证时，您可以使用此功能。