超级图特定功能

GraphOS Studio提供了工具，以帮助多个团队合作完成超级图及其子图。

超级图变体

每个变体的 Studio超级图都有自己的子图模式、超级图模式、更改历史和指标。

超级图的不同变体甚至可以具有完全不同的子图集合：

这有助于您在非生产环境中测试添加新的子图（或删除现有的子图）。

当您发布子图的模式时，您可以指定要向其发布该模式超级图变体。

添加变体

您可以通过以下方式向现有的GraphOS超级图中添加新的变体：

• 在GraphOS Studio中（仅限云超级图）
• 通过Rover CLI

在GraphOS Studio中添加变体

1. 转到您的超级图在Studio中的设置页面，并导航到此图 > 变体。

2. 单击添加变体。

3. 在出现的对话框中，提供变体名称并单击继续。

4. 提供您的第一个子图的路由URL（这是新变体的路由器与子图通信使用的URL），以及一个子图名称。

   • 始终创建新超级图变体也需要创建该变体的第一个子图。

5. 如果工作室无法从路由URL自动获取 子图's 架构，请点击 高级选项 以通过其他方式提供架构（例如直接粘贴架构或检查本地运行的服务器）。

6. 点击 添加新变体。操作完成后，您的新 变体 将在工作室的您所在组织的主页上列出。

通过Rover CLI添加变体

要使用 Rover 将新变体添加到您的 supergraph，您需要发布其第一个 子图 的架构！为此，您使用与 更新现有子图架构 相同的Rover命令。唯一的区别是您将新 变体 的名称提供给命令。

了解发布子图架构。

管理子图

创建 云supergraph（或其变体）后，您可以从变体的 子图 页面上查看其关联的子图列表：

列表包括每个 子图 的名称和路由URL，以及每个子图架构的类型和 字段 计数。

添加新子图

您可以通过以下方式将您的新的 子图 添加到您的 GraphOS supergraph：

• 在GraphOS Studio中（仅适用于云 supergraphs）
• 通过Rover CLI

在GraphOS Studio中添加子图

1. 转到您变体的 子图 页面。

2. 点击 添加子图。

3. 在出现的对话框中，提供 子图 的 路由URL（这是 supergraph 的 router 与子图通信使用的URL）以及 子图名称。

4. 如果工作室无法从路由URL自动获取 子图's 架构，请点击 高级选项 以通过其他方式提供架构（例如直接粘贴架构或检查本地运行的服务器）。

5. 点击 添加子图。操作完成后，您的新 子图 将列在子图页面上。

通过Rover CLI添加子图

要将子图添加到您的 supergraph 中使用 Rover，您需要发布子图的架构！为此，您使用与 更新现有子图架构 相同的Rover命令。唯一的区别是您将新 子图 的名称提供给命令。

了解发布子图架构。

修改子图

从您的 子图 页面，您可以修改现有子图的路由URL：

1. 打开您想修改的子图的 ••• 菜单：

   

2. 点击 编辑路由URL。

3. 在出现的对话框中，提供新的URL并点击 更新。

   • 您的路由器将自动开始使用新的URL与您的子图进行通信。

如果您需要修改现有的子图，请使用 Rover CLI。了解 rover subgraph 命令。

删除子图

您可以从您云超图的一个版本中删除现有的子图。

1. 版本将自动尝试使用所有剩余子图的模式来组合更新的超图模式。

   • 工作室将显示此尝试的结果，如果有错误，您可以取消删除。

2. 如果组合成功，则版本的路由器将自动开始使用更新的超图模式。这意味着客户端无法再查询仅在已删除子图中定义的字段。

   如果组合失败，则路由器将继续使用其现有的超图模式。这意味着客户端可以继续查询已删除子图中的字段，直到剩余子图模式更新为成功组合。

⚠️ 重要注意事项

• 删除子图可能会破坏现有客户端！此操作相当于从您的超图中删除所有子图类型和字段（除非它们也定义在另一个子图中）。如果一个客户端发送包含这些类型和字段的任何操作，则路由器将拒绝该操作。

  • 要安全地删除模式定义，请了解 模式检查

• 在工作室中删除子图不会影响您的实际运行子图实例。它只会删除您的路由器对该实例及其相应模式字段的了解。

在工作室中删除的步骤

1. 转到对应版本子图的子图页面。

2. 点击要删除的子图右侧的•••按钮：

   

3. 点击删除子图。Studio将尝试创建一个新的超图模式，其中不包括您要删除的子图。

4. 会出现一个确认对话框，显示出现的任何组合错误。如果您确实要删除子图，请输入其名称并点击删除子图。

查看字段的来源子图

在Studio中的“模式 > 参考”页面显示了一个表格，其中包含您的超图's的类型和字段。此表包括一个子图's列，列出每个类型和字段定义的子图：

单击类型或字段的子图链接会带您到定义其对应的子图模式的位置

如果使用的@contact指令来指定子图的负责人联系信息，将鼠标悬停在子图名称上会显示其联系信息，从而可以联系相应的团队：

查看子图SDL

在Studio中的“模式 > SDL”页面显示每个与您的超图关联的模式类型的原始SDL。这是一个API模式、一个超图模式和子图模式。

从该页面，您可以

• 查看组成超图的元数据，以及每个子图的元数据（例如端点URL和最近的模式注册日期）
• 识别定义了您的API中的任何类型或字段的子图，并与团队成员分享链接
• 搜索类型和字段
• 下载子图的SDL副本用于本地开发
• 过滤掉注释和已弃用字段以提高扫描

子图的联系信息

您可以使用@contact指令将您的团队联系信息添加到子图模式中。在Studio中显示这些信息，这有助于其他团队知道如何与谁联系以获取子图的帮助：

联系信息包括团队或个人的名称，以及可选的描述和自定义URL。

将@contact指令添加到您的子图

要在您的subgraph模式中使用@contact指令，您首先需要在模式中定义该指令。将以下定义添加到每个subgraph模式中：

1
"Annotate a schema with contact information for the subgraph owner"
2
directive @contact(
3
  "Contact title of the subgraph owner"
4
  name: String!
5
  "URL where the subgraph's owner can be reached"
6
  url: String
7
  "Other relevant notes can be included here; supports markdown links"
8
  description: String
9
) on SCHEMA

现在，您可以将@contact指令应用到每个subgraph模式的特殊schema对象中。如果您的模式还没有定义此对象，可以像这样添加它：

1
extend schema
2
  @contact(
3
    name: "Acephei Server Team"
4
    url: "https://myteam.slack.com/archives/teams-chat-room-url"
5
    description: "send urgent issues to [#oncall](https://yourteam.slack.com/archives/oncall)."
6
  )

支持的@contact字段

已知@contact限制

• 要将@contact指令提供给Apollo，您必须通过提供本地.graphql文件作为rover subgraph publish命令的--schema选项来发布您的subgraph模式。
  • 如果您向命令提供 introspection 结果，则@contact指令将不包括在该结果中。

查看联系信息

在您发布包含@contact指令的subgraph模式后，联系信息将包含在Studio的Schema > SDL选项卡中显示的元数据中：

在Schema > Reference选项卡中，您在悬停于类型或字段的subgraph链接上时，也会看到一个联系卡片：

模式标记

在你的 子图模式中，你可以使用 @tag 指令为类型或字段标记任意字符串值：

1
type Product {
2
  id: ID!
3
  name: String!
4
  codename: String! @tag(name: "internal")
5
}

默认情况下，这些标记会被从 API 模式 中移除，这些模式作为组合过程的一部分生成。这意味着标记信息对外部客户端查询你的超图是不可见的。

如果客户端需要看到标签信息（例如，帮助 文档 你的 API），你可以在 Studio 中通过以下步骤对变体启用此功能：

1. 前往 GraphOS Studio 中你的变体的 设置 页面。
2. 在 常规 选项卡上，点击 编辑配置。将弹出一个更新构建配置对话框。
3. 如果你有一个 Federation 1 超图，在 指令 下启用 @tag 指令的切换器（对于 Federation 2 超图，这一步不是必须的）。
4. 在 构建设置 下，启用名为 在 Schema 参考和探索者中向消费者显示 @tag 指令的全部使用情况 的切换器。
5. 点击 保存。

在你让你的 @tag 指令可见后，你可以在 Studio 的模式和探索者标签页中查看它们。

在 Schema > Reference 标签页中，每个类型和字段都会显示标签：

标签也在探索者的 文档 标签页中可见：

探索器中的超图支持

GraphOS Studio 探索器提供了对处理超图的增强支持：

• 你可以通过检查响应面板中的 查询计划 来预览你的超图路由器如何为一个操作解析数据。
• 当你正在探索者中构建 操作 时，通过在探索者的设置标签页中启用子图提示，你可以看到操作中每个字段最初来自哪个子图。

查看组合错误

如果一个超图最近的子图模式集合无法组合，则 Studio 中超图页面的顶部将显示 BUILD FAILED 标签：

你可以点击这个标签来查看必须解决的错误，以使组合成功。有关更多信息，请参阅 组合错误参考。