云路由器配置

了解如何在 GraphOS Studio 中配置云路由器

创建云层supergraph后，您可以从“云路由器”页面管理其路由器配置。GraphOS Studio.

“常规”选项卡显示了以下信息：

您的路由器GraphQL端点的URL
- 每个云路由器的URL都在子域apollographos.net上。
您的路由器的当前状态和发布历史

从“配置”选项卡中，您可以管理以下内容：

密钥
您的路由器的基于YAML的配置

管理密钥

您可以将可用的密钥字符串存储在您的路由器的YAML配置中。例如，您可能存储一个授权令牌，路由器需要将其包含在每个对子图的请求中。

要添加新密钥，单击保存密钥。

在弹出的对话框中，输入密钥的名称和值。保存密钥后，您无法查看密钥的值，因此请确保在保存之前值是正确的。准备好后，单击保存密钥。

您的密钥将被加密并存储。然后您可以在路由器的YAML配置中使用密钥的值。

以下示例YAML配置使用名为MY_SECRET的密钥的值：

1
headers:
2
  all:
3
    request:
4
      - insert:
5
          name: 'subgraph-token'
6
          value: '${env.MY_SECRET}'

路由配置 YAML

您可以在路由配置 YAML中进行配置，以改变您路由器在云路由器标签或页面上的行为。

在无服务器计划中，您可以配置：

HTTP 头部，这些头部信息会被路由器发送到您的子图。 addressed to your subgraphs
CORS 规则，用于连接到路由器的基于浏览器的应用程序
子图错误包含，向查询客户端（包括 Apollo 探索器）暴露子图错误

智能感知，允许解析智能感知查询

专用和企业计划提供了更多配置选项。

如果您需要更高级的路由器定制，请联系我们，了解您的专用和企业计划选项。

HTTP 头部规则

您可以为每个子图配置路由器请求中包含哪些 HTTP 头部。除了一般性子图头部规则外，您还可以定义针对所有子图的规则。

您在路由配置 YAML中定义头部规则，如下所示：

1
# ...other configuration...
2
headers:
3
  all: # Header rules for all subgraphs
4
    request:
5
      - propagate:
6
          matching: ^upstream-header-.*
7
      - remove:
8
          named: 'x-legacy-account-id'
9
  subgraphs:
10
    products: # Header rules for just the products subgraph
11
      request:
12
        - insert:
13
            name: 'router-subgraph-name'
14
            value: 'products'

支持的头部规则

云路由支持以下类型的头部规则

`传播`

允许您选择性地传递客户端请求中包含到路由器的头部。

您可以根据匹配的正则表达式模式来指定要传播哪些头部：

1
- propagate:
2
    matching: .*

ⓘ 注意

路由器在按照模式传播时，永远不会传播所谓的端到端头信息，比如 Content-Length。

或者，您可以通过named选项提供静态字符串。这些named配置具有额外的灵活性，因为它们支持以下选项：

default：客户端未发送值时设置的值
rename：将头键重命名为提供的值

1
- propagate:
2
    named: 'x-user-id'
3
    default: 'abc123'
4
    rename: 'account-id'

`删除`

允许您有选择地从客户端请求路由器时包含的头信息中删除头部信息。像propagate一样，此选项可以匹配静态字符串或正则表达式。

1
# Do not send this subgraph the "Cookie" header.
2
- remove:
3
    named: 'Cookie'
4
- remove:
5
    # Remove headers that include the legacy 'x-' prefix.
6
    matching: ^x-.*$

`插入`

允许您向特定的子图请求中添加自定义头部。这些头部始终是静态字符串，源自路由器，而不是客户端。

1
- insert:
2
    name: 'sent-from-our-apollo-router'
3
    value: 'indeed'

规则排序

头部规则按声明的顺序应用，后续规则可以覆盖早期规则的影响。考虑以下示例

❌

bad_configuration.yaml

1
headers:
2
  all:
3
    request:
4
      - remove:
5
        named: 'test'
6
      - propagate:
7
        matching: .*

在此示例中，首先从传播头列表中删除名为test的头。但是，当前的传播头列表为空！接下来，propagate规则将所有头部添加到传播列表中，包括test。

要正确地从传播列表中删除头部，确保您的remove规则定义在所有propagate规则之后：

✅

good_configuration.yaml

1
headers:
2
  all:
3
    request:
4
      - propagate:
5
        matching: .*
6
      - remove:
7
        named: 'test'

按照这个排序方式，首先将所有头部添加到传播列表中，然后删除test头部。

示例

以下是一个完整示例，演示了所有支持的headers配置选项：

1
headers:
2
  # Header rules for all subgraphs
3
  all:
4
    request:
5
      # Propagate matching headers
6
      - propagate:
7
          matching: ^upstream-header-.*
8
      # Propagate matching headers
9
      - propagate:
10
          named: 'some-header'
11
          default: 'default-value'
12
          rename: 'destination-header'
13
      # Remove the "x-legacy-account-id" header
14
      - remove:
15
          named: 'x-legacy-account-id'
16
      # Remove matching headers
17
      - remove:
18
          matching: ^x-deprecated-.*
19
      # Insert the 'my-company' header
20
      - insert:
21
          name: 'my-company'
22
          value: 'acme'
23
  # Subgraph-specific header rules
24
  subgraphs:
25
    products:
26
      request:
27
        # Calls to the products subgraph have the "router-subgraph-name" header set to `products`.
28
        - insert:
29
            name: 'router-subgraph-name'
30
            value: 'products'
31
    accounts:
32
      request:
33
        # Calls to the accounts subgraph have the "router-subgraph-name" header set to `accounts`.
34
        - insert:
35
            name: 'router-subgraph-name'
36
            value: 'accounts'

CORS设置

ⓘ 注意

如果您的路由器仅服务于非基于浏览器的客户端，您可能不需要修改默认的CORS配置。

有关CORS的更一般介绍和常见考虑事项，请参阅以下章节

默认情况下，路由器仅启用 GraphOS Studio 以发起与它的浏览器连接。如果您的 supergraph 为其他基于浏览器的应用程序提供数据，您需要在 cors 部分中执行以下操作之一，以 路由器配置 YAML:

将这些网络应用程序的来源添加到路由器的允许列表中 origins.
- 如果已知有限数量的网络应用程序消耗您的云 supergraph，则使用此选项。
将匹配这些网络应用程序来源的正则表达式添加到路由器的允许列表中 origins.
- 如果想要匹配模式，此选项很有用，请参见以下示例，它匹配特定命名空间的下级域名。
启用 allow_any_origin 选项。
- 如果您的超级图是具有任意多个网络应用程序消费者的公开API，则使用此选项。
- 启用此选项后，路由器将发送通配符（*）值作为 Access-Control-Allow-Origin 头。这使任何网站都可以发起与它的浏览器连接（但它们无法提供cookies或其他凭证）。
如果客户端需要使用cookies来对他们的请求进行认证，则必须使用 origins + match_origins 选项。

以下代码段包括每个选项的示例（使用 allow_any_origin 或 origins + match_origins）：

1
cors:
2
  # Set to true to allow any origin
3
  # (Defaults to false)
4
  allow_any_origin: true
5

6
  # List of accepted origins
7
  # (Ignored if allow_any_origin is true)
8
  # (Defaults to the GraphOS Studio url: `https://studio.apollographql.com`)
9
  #
10
  # An origin is a combination of scheme, hostname and port.
11
  # It does not have any path section, so no trailing slash.
12
  origins:
13
    - https://www.your-app.example.com
14
    - https://studio.apollographql.com # Keep this so GraphOS Studio can run queries against your router
15
  match_origins:
16
    - 'https://([a-z0-9]+[.])*api[.]example[.]com' # any host that uses https and ends with .api.example.com

您也可以通过将 origins 设置为空列表来完全关闭CORS：

1
cors:
2
  origins: []

传递凭证

如果您的路由器需要请求包含用户的凭证（例如，通过cookies），您需要修改您的CORS配置以告诉浏览器这些凭证被允许。

您可以通过设置 Access-Control-Allow-Credentials HTTP头为 true 以启用凭证。

ⓘ 注意

您的路由器必须指定单个来源以支持认证请求。如果您的路由器启用了allow_any_origin，则浏览器将拒绝发送凭证。

要允许浏览器将凭证发送到您的路由器，设置allow_credentials为true，如下所示：

1
cors:
2
  origins:
3
    - https://www.your-app.example.com
4
    - https://studio.apollographql.com
5
  allow_credentials: true

有关从Apollo 客户端发送cookie和授权头的示例，请参阅身份验证。

所有 `cors` 选项

以下代码片段显示了您的路由器的所有 CORS 配置默认值：

1
#
2
# CORS (Cross Origin Resource Sharing)
3
#
4
cors:
5
  # Set to true to allow any origin
6
  allow_any_origin: false
7

8
  # List of accepted origins
9
  # (Ignored if allow_any_origin is set to true)
10
  #
11
  # An origin is a combination of scheme, hostname and port.
12
  # It does not have any path section, so no trailing slash.
13
  origins:
14
    - https://studio.apollographql.com # Keep this so GraphOS Studio can still run queries against your router
15

16
  # Set to true to add the `Access-Control-Allow-Credentials` header
17
  allow_credentials: false
18

19
  # The headers to allow.
20
  # Not setting this mirrors a client's received `access-control-request-headers`
21
  # This is equivalent to allowing any headers,
22
  # except it will also work if allow_credentials is set to true
23
  allow_headers: []
24

25
  # Allowed request methods
26
  methods:
27
    - GET
28
    - POST
29
    - OPTIONS
30

31
  # Which response headers are available to scripts running in the
32
  # browser in response to a cross-origin request.
33
  expose_headers: []

响应 `Vary` 头部

插件可以设置响应Vary头部。如果所有插件处理完毕后，没有响应Vary头部，则路由器将添加一个值设置为origin的头部。

Subgraph 错误包含

默认情况下，您的云supergraph在其响应中删除子图错误详情。路由器将返回一个默认错误，如下所示：

1
Subgraph errors redacted

此删除可以防止敏感信息泄露给客户。

如果您希望将子图错误传播给客户，则可以在路由器的 YAML 配置中添加include_subgraph_errors键，如下所示：

1
include_subgraph_errors:
2
  all: true # Propagate errors from all subraphs
3
  subgraphs:
4
    products: false # Do not propagate errors from the products subgraph

位于subgraphs键下的任何配置都优先于位于all键下的配置。在上面的示例中，除了products子图外，所有子图的子图错误都被包含在内。

内省

默认情况下，您的云supergraph不解析内省查询。您可以如下启用内省：

1
# Do not enable introspection for production workloads!
2
supergraph:
3
  introspection: true

概述