加入我们，从10月8日至10日在纽约市，学习有关GraphQL Federation和API平台工程的最新技巧、趋势和新闻。参加2024年纽约市的GraphQL峰会
文档
免费开始

Rover配置

带有GraphOS的Rover CLI配置指南

通过GraphOS进行认证

1. 获取API密钥

所有 命令与 GraphOS 进行通信需要API密钥。 支持两种类型的API密钥：个人API密钥 和 图API密钥。

  • 在本地开发机器上，使用一个 。
  • 在CI等共享环境中，使用一个 。

了解如何获取API密钥。

2. 向Rover提供API密钥

您可以通过 Rover 命令（推荐用于本地开发）或将 环境变量（推荐用于自动化和CI）来提供API密钥。

如果通过两种方法都提供了API密钥，则环境变量具有优先权。

通过auth 命令

您可以通过运行以下命令向Rover提供API密钥：

rover config auth

此方法推荐用于本地开发。如果您想要使用Rover 配置多个API密钥，您可以分配给不同的配置配置文件。

为了防止API密钥出现在您的终端命令历史中，auth命令是交互式的。因为它是交互式的，我们建议在类似CI的自动化环境中使用环境变量。

使用环境变量

您可以通过设置APOLLO_KEY环境变量的值来将API密钥提供给Rover。此方法适用于CI等自动化环境。

配置配置文件

您可以在Rover中创建多个配置配置文件。每个配置配置文件都有一个关联的API密钥，因此您可以在与不同的交互时使用不同的配置配置文件。

要指定要用于特定命令的配置配置文件，请使用--profile标志：

rover graph check my-company@prod --profile work

如果您没有为命令指定配置配置文件，Rover将使用默认配置文件（命名为default）。

要查看所有与配置配置文件相关的命令，请运行以下命令

rover config --help

了解更多关于 rover config 命令。

日志记录

Rover支持以下日志级别，按严重性递减排序：

  • 错误
  • 警告
  • 信息
  • 调试
  • 跟踪

默认情况下，Rover记录error、warn和info消息。您可以通过设置--log标志来为命令配置此行为，以设置其最小日志级别：

rover graph check my-graph@prod --schema ./schema.graphql --log debug

如果您觉得Rover的日志消息无用或不清晰，请在本地的GitHub issues！

配置输出

默认情况下，Rover将命令的输出打印到stdout的纯文本中。如果它认为是由人操作的（它检查终端是否是TTY），它还会将该输出的描述符打印到stderr。

有关stdout的更多信息，请参阅约定。

每个 Rover 命令都支持两种配置输出行为的方式：

  • --format，用于设置输出格式（普通文本plain或json）
  • --output，用于将命令的输出写入文件而不是stdout

JSON 输出

--format选项是在 Roverv0.11.0版本中加入的。Rover 更早的版本使用--output选项来设置输出格式。

Rover 的当前版本仍然支持使用--output来这种方式，但这种支持已被弃用，将在未来的版本中删除。

要获取对 Rover 输出的更多编程控制，您可以在任何命令中传递--format json。Rover 的 JSON 输出具有以下最小结构：

成功示例
{
  "json_version": "1",
  "data": {
    "success": true
  },
  "error": null
}
错误示例
{
  "json_version": "1",
  "data": {
    "success": false
  },
  "error": {
    "message": "An unknown error occurred.",
    "code": null
  }
}

如上图所示，一些 rover错误包含一个null错误代码。尽管如此，您的脚本应该根据它们的code匹配特定的错误，而不是根据它们的message（错误信息字符串可能在json_version不增加的情况下更改）。

如果您经常遇到未编码的错误，请提交一个issue。

JSON输出字段

名称
类型		描述
json-version

字符串

指示JSON输出结构的版本。脚本可以检查此值以检测破坏性更改。

可能会在不增加json_version的情况下向Rover的JSON结构添加非破坏性更改。

data

对象

表示命令的结果。

始终包含至少一个success布尔字段

请注意，即使data.success为true，也可能存在error。某些命令（例如，subgraph publish）可能会产生组合错误，即使命令的主要行动（例如，将模式发布到Apollo）成功。请参阅特定于命令的JSON输出。

错误

对象 | null

表示命令执行过程中发生的任何错误（如果没有错误发生，则为null）。

如果存在，则始终包含至少message和code字段

特定于命令的JSON输出

以下是一个rover subgraph publish的成功输出示例：

成功示例
{
  "json_version": "1",
  "data": {
    "api_schema_hash": "a1bc0d",
    "supergraph_was_updated": true,
    "subgraph_was_created": true,
    "subgraph_was_updated": true,
    "success": true
  },
  "error": null
}

以下是一个错误输出示例

错误示例
{
  "json_version": "1",
  "data": {
    "api_schema_hash": null,
    "subgraph_was_created": false,
    "subgraph_was_updated": true,
    "supergraph_was_updated": false,
    "success": true
  },
  "error": {
    "message": "Encountered 2 build errors while trying to build subgraph \"subgraph\" into supergraph \"name@current\".",
    "code": "E029",
    "details": {
      "build_errors": [
        {
          "message": "[Accounts] -> Things went really wrong",
          "code": "AN_ERROR_CODE",
          "type": "composition",
        },
        {
          "message": "[Films] -> Something else also went wrong",
          "code": null,
          "type": "composition"
        }
      ]
    }
  }
}

此特定error对象包含有关出错的详细信息。请注意，即使在执行此命令时发生错误，data.success仍然是true。这是因为错误是与相关的错误。尽管组合失败，但子图发布本身是成功的。

示例 jq 脚本

您可以将--format json标志与jq命令行工具组合，以创建强大的自定义工作流。例如，这个代码片段演示了将rover {sub}graph check my-graph --format json的输出转换为Markdown。

写入文件

使用--output选项，您可以指定文件的存储位置以写入Rover命令的输出：

rover supergraph compose --output ./supergraph-schema.graphql --config ./supergraph.yaml

如果指定的文件已存在，Rover将覆盖它。

此功能可在Rover v0.11.0及以后的版本中使用。在更早的Rover版本中，--output选项提供了现在由--format选项提供的功能。

当前版本的Rover仍支持使用--output，但该支持已被弃用，并在未来的版本中将被移除。

设置配置存储位置

Rover将您的配置存储在本地文件中，并在进行请求时使用它。默认情况下，此文件存储在操作系统默认配置目录中的.sensitive文件中。

您可以通过设置APOLLO_CONFIG_HOME环境变量来覆盖此文件的存储位置。这对于没有访问默认操作系统目录的CI系统可能很有用。

# Stores config in ./myspecialconfig/rover.toml
APOLLO_CONFIG_HOME=./myspecialconfig/

Git上下文

漫游器会在您运行check或publish命令时，向您将关于Git环境的非机密信息发送到GraphOS。此信息会在Studio UI的相关视图中显示，以便更轻松地追踪模式变更的提议或发布位置：

Checks info in GraphOS Studio

此Git信息包括

  • 您Git仓库的远程URL（已移除任何用户名/密码）
  • 当前提交的SHA
  • 当前SHA的提交者
  • 当前分支名称

要查看这些值，请使用check或publish命令并指定--log trace选项。

重写

此信息均不应该敏感，但如果你想要重写这些值，可以设置以下环境变量：

  • APOLLO_VCS_REMOTE_URL
  • APOLLO_VCS_BRANCH
  • APOLLO_VCS_COMMIT
  • APOLLO_VCS_AUTHOR

非Git版本控制

如果您使用的是Git之外的版本控制系统，您可以使用Git上下文中描述的环境变量来设置与您的版本控制工具相关的类似信息。

当前，GraphOS Studio只完全支持Git。

绕过TLS/SSL验证

在某些配置（特别是在内部网络中），您可能需要漫游器通过加密通道（例如HTTPS）进行通信，同时避免对主机名进行严格的数字证书验证。您甚至可能需要完全绕过数字证书验证。

这不建议使用，且被认为安全性大大降低。但是，如果必要时，您可以使用以下标志来配置漫游器如何验证HTTPS请求：

  • 启用--insecure-accept-invalid-hostnames标志将禁用主机名验证。如果未使用主机名验证，则任何站点上的任何有效证书都可以从任何其他站点信任使用。这引入了中间人攻击的严重漏洞。

  • 启用--insecure-accept-invalid-certs标志将禁用证书验证。如果信任无效的证书，则任何站点上的任何证书都可以信任使用。包括过期证书。这引入了严重的漏洞，应该作为最后的手段使用。

增加请求超时时间

默认情况下，Rover将在30秒后超时对GraphOS Studio API和您的图端点的请求。如果您正在执行可能需要超过30秒处理时间的命令，您可以使用--client-timeout选项来增加此超时：

rover subgraph check my-graph --validation-period 1m --client-timeout=60

支持的环境变量

您可以通过以下列出的环境变量配置Rover's行为。

如果存在，则环境变量的值优先于其他所有配置该行为的方法。

名称值
APOLLO_HOME用于存放Rover二进制文件的父目录的路径。默认值是您操作系统的默认主目录。Rover将在指定的目录内创建一个名为.rover的文件夹以安装自己。
APOLLO_CONFIG_HOME存放Rover配置的路径。默认值是您操作系统的默认配置目录。
APOLLO_KEYRover用来验证GraphOS Studio的API密钥。
APOLLO_TELEMETRY_DISABLED如果您不想让Rover收集匿名使用数据，则设置为true。
APOLLO_VCS_REMOTE_URL您的项目远程仓库的URL。请查阅Git上下文。
APOLLO_VCS_BRANCH受版本控制分支的名称。请查阅Git上下文。
APOLLO_VCS_COMMIT提交的长标识符（Git中的SHA）。请查阅Git上下文。
APOLLO_VCS_AUTHOR提交者的姓名和电子邮件地址（例如，Jane Doe <[email protected]>）。请查阅Git上下文。
NO_EMOJI如果您不想让Rover打印表情符号，请将其设置为1。
NO_COLOR如果您不想让Rover打印颜色，请将其设置为1。
上一个
安装
下一个
代理配置
评分文章评分在GitHub上编辑编辑论坛Discord

©2024Apollo Graph Inc.，即Apollo GraphQL。

隐私政策

公司

资源

联系