title: grpc-web keywords:

  • Apache APISIX
  • API 网关
  • Plugin
  • gRPC Web
  • grpc-web description: 本文介绍了关于 Apache APISIX grpc-web 插件的基本信息及使用方法。

描述

grpc-web 插件是一个代理插件，可以处理从 JavaScript 客户端到 gRPC Service 的 gRPC Web 请求。

属性

名称类型必选项默认值描述
cors_allow_headersstring否“content-type,x-grpc-web,x-user-agent”允许跨域访问时请求方携带哪些非 CORS 规范 以外的 Header。如果你有多个 Header，请使用 , 分割。

启用插件

你可以通过如下命令在指定路由上启用 gRPC-web 插件：

:::note

您可以这样从 config.yaml 中获取 admin_key 并存入环境变量：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri":"/grpc/web/*",
    "plugins":{
        "grpc-web":{}
    },
    "upstream":{
        "scheme":"grpc",
        "type":"roundrobin",
        "nodes":{
            "127.0.0.1:1980":1
        }
    }
}'

:::info IMPORTANT

在使用 gRPC Web 代理插件时，路由必须使用前缀匹配模式（例如：/* 或 /grpc/example/*），因为 gRPC Web 客户端会在 URI 中传递 proto 中声明的包名称、服务接口名称、方法名称等信息（例如：/path/a6.RouteService/Insert）。

因此，在使用绝对匹配时将无法命中插件和提取 proto 信息。

:::

测试插件

请参考 gRPC-Web Client Runtime Library 或 Apache APISIX gRPC Web Test Framework 了解如何配置你的 Web 客户端。

运行 gRPC Web 客户端后，你可以从浏览器或通过 Node.js 向 APISIX 发出请求。

:::note

请求方式仅支持 POST 和 OPTIONS，详细信息请参考：CORS support 。

内容类型支持 application/grpc-web、application/grpc-web-text、application/grpc-web+proto、application/grpc-web-text+proto，详细信息请参考：Protocol differences vs gRPC over HTTP2 。

:::

删除插件

当你需要禁用 grpc-web 插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "uri":"/grpc/web/*",
    "plugins":{},
    "upstream":{
        "scheme":"grpc",
        "type":"roundrobin",
        "nodes":{
            "127.0.0.1:1980":1
        }
    }
}'