HTTP 绑定规范

替代方法

服务调用 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" # 可选

元数据字段说明

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

• Secret 存储引用：

  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 编码字符串作为字段的值提供。

绑定支持

此组件支持具有以下 HTTP 方法/动词 的 输出绑定：

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

请求

操作元数据字段

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

检索数据

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

{
  "operation": "get"
}

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

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

响应

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

示例

请求基本 URL

• Windows
• Linux

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>

请求特定路径

• Windows
• Linux

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 绑定，并使用以下 JSON 正文：

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

示例

发布新记录

• Windows
• Linux

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 sidecar 信任服务器的 SSL 证书，HTTP 绑定也可以与 HTTPS 端点一起使用。

1. 将绑定 URL 更新为使用 https 而不是 http。
2. 如果需要添加自定义 TLS 证书，请参考 如何：在 Dapr sidecar 中安装证书，在 sidecar 中安装 TLS 证书。

示例

更新绑定组件

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

在 sidecar 中安装 TLS 证书

• Self-Hosted
• Kubernetes

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" # 将证书文件夹挂载到 sidecar 容器的 /certificates
    environment:
      - "SSL_CERT_DIR=/certificates" # 将环境变量设置为证书文件夹的路径
    depends_on:
      - my-app

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

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" # 将证书文件夹挂载到 sidecar 容器的 /certificates
        dapr.io/env: "SSL_CERT_DIR=/certificates" # 将环境变量设置为证书文件夹的路径
    spec:
      volumes:
        - name: cert-vol
          secret:
            secretName: myapp-cert
...

安全地调用绑定

• Windows
• Linux

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>

使用 mTLS 或启用客户端 TLS 认证以及 HTTPS

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

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

• 如果提供了文件路径，则读取文件并使用其内容。
• 如果提供了 PEM 编码字符串，则直接使用该字符串。

当这些字段被配置时，Dapr sidecar 在 TLS 握手过程中使用提供的证书来认证自己。

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

• RenegotiateNever
• RenegotiateOnceAsClient
• RenegotiateFreelyAsClient

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

当服务器需要 mTLS 或客户端 TLS 认证时，可以使用此功能。

相关链接

• Dapr 组件的基本架构
• 绑定构建块
• 如何：使用输入绑定触发应用程序
• 如何：使用绑定与外部资源接口
• 绑定 API 参考
• 如何：在 Dapr sidecar 中安装证书