开始使用 GraphOS

你好！👋 这个快速入门可以帮助您使用 GraphOS 和您的第一个超级图。此设置不需要付费计划。

要完成这些步骤，以下选项之一可用

• 您运行的 URLGraphQL 服务器，已启用 introspection。
• 您的 GraphQL 服务器 的 schema，作为纯文本 SDL

如果您没有这些，没问题！您仍然可以用示例 GraphQL 服务器 来尝试 GraphOS。为此，提供以下步骤中所有标记为🚀 示例设置的值。

1. 创建您的 Apollo 帐户

GraphOS Studio 是与 GraphOS 平台交互的主要网络界面。我们将在此教程的每个步骤中使用 Studio，首先是创建一个 Studio 帐户。

1. 前往 studio.apollographql.com 并点击 开始吧。

2. 选择注册方式 - 使用 GitHub 或使用电子邮件和密码。然后 Studio 会显示一个注册表单。具体细节取决于您选择的注册方式。

3. 填写表格，并点击 创建账户。默认情况下，您的账户位于 无服务器（免费）计划。

2. 创建您第一个超级图

现在您已有了一个 GraphOS Studio 账户，但它还没有任何图。接下来的步骤将指导您创建一个 cloud supergraph。云 超级图会自动在您的 API 前面配置一个 GraphOS 路由器。客户端会查询您的路由器而不是直接查询您的 API。

在这个架构中，您可以将多个 API 合并成一个单独的 图，所有操作都由 路由器 协调：

如果您是在现有账户中创建新的云 supergraph，请按照 该部分 中的步骤进行。否则，继续以下步骤。

从新账户开始

1. Studio 将提示您 连接您的 API 或 尝试一个示例图。如果您有正在运行的 GraphQL 服务器 的 URL，请选择 连接 API。否则，您可以选择 尝试一个示例图，Apollo 将为您创建一个示例 graph 以进行测试。

2. 提供您的 GraphQL API 的端点 URL。这是客户端应用程序当前用于查询您的 API 的相同 URL。提供 URL 后，Studio 会通过 introspection 尝试从其中获取您的 API 规范。结果将显示在文本框下方。

   • 如果您的 GraphQL 服务器 需要某些 HTTP 头部信息以便 Studio 进行 introspection，请点击 提供 HTTP 头部 并指定它们。

3. 提供您服务的 名称。该名称应该反映您 API 所提供的数据或功能，并且应该唯一地标识您的 API，以便于您稍后可以向超级图添加其他 API。

   ⓘ 注

   服务名称是不可变的。

4. 点击 继续。

   • 如果 继续 按钮不可用，则表示 Studio 没有获取到您的 API 规范。如有必要，您可以通过 上传您的规范 来绕过 introspection。选择此选项后，您可以手动复制和粘贴您的规范，或拖放一个 .gql 或 .graphql文件。

5. 为您的新的graph提供名称和ID。

   • 名称将在整个Studio中显示，帮助您的团队能够区分不同的graphs。您可以在任何时间更改graph的名称。
   • ID是不可变的，必须在Apollo的所有内容中唯一。确保它以字母开头，并且只包含字母、数字和破折号。您将使用ID来从各种工具中引用您的graph，例如Rover CLI。

6. 点击 继续。

您现在已经创建了一个云supergraph，该supergraph列在您的组织Graphs标签页中：

您的GraphQL API现在是该云supergraph中的第一个subgraph。跳转到下一步了解关于variants的信息。

从现有账户

1. 从您的GraphOS Studio，导航到Graphs标签页（如果尚未打开）。在右上角选择+创建新Graph。

2. 点击连接您的GraphQL API。

3. 在出现的对话框中，提供您的GraphQL API的Endpoint URL。

   • 这是客户端应用程序目前用来查询您的API的相同URL。
   • 如果您没有URL，您可以使用https://flyby-locations-sub.herokuapp.com/作为示例。

   提供URL后，Studio将使用introspection从其中获取您的API模式。一旦获取成功，输入将显示绿色勾选。

4. （可选）对于以下场景，您可以点击高级选项：

• 如果您的 GraphQL 服务器 需要某些 HTTP 头部信息以便 Studio 进行 introspection，请点击 提供 HTTP 头部 并指定它们。
• 您可以通过点击直接提供您的schema来提供您的API的文本SDL。
• 最后，您可以选择使用本地introspection来提供本地URL并一次性introspection您的模式。

5. 为您的API提供一个Subgraph名称。此名称在后续添加到supergraph的任何其他API中都是唯一的。该名称应反映您的API提供的数据或功能。

   • 如果您正在使用https://flyby-locations-sub.herokuapp.com/示例URL，您可以输入Locations作为subgraph名称。

   ⓘ 注

   子图名称是不可变的。

6. 点击下一个。

   • 如果“下一个”按钮不可用，表明 Studio 还未获取到您的 API 架构！请确保使用步骤 3 和 4 中的方法之一提供它。

7. 在出现的对话框中，为您的新的超级图提供名称和 ID。

   • 名称在 Studio 中显示，有助于您的团队区分不同的图。您可以随时更改图的名称。
   • ID 不可变，必须在 Apollo 的所有图中是唯一的。请确保它以字母开头，并且只包含字母、数字和连字符。您将使用该 ID 从各种工具中引用您的图，例如 Rover CLI。

8. 点击创建超级图。

您现在已创建第一个云超级图，您可以在组织中的图标签页中查看它：

您的 GraphQL API 现在这云超级图中的第一个子图。

3. 了解您的变体

当您创建超级图时，也创建了它的第一个变体。GraphOS 中的每个图都有一个或多个变体，代表不同的运行环境，如 staging 或者生产。每个变体都有一个您设置的名称，或者默认有current。

让我们看看 Studio 提供的视图，帮助您了解您的变体：

在您的图标签页中，点击您图的 current 变体。这打开了变体的 README 页面。

README 框架极大的帮助团队了解如何使用超级图。它支持 Markdown 语法，就像 Git 仓库中的典型 README 一样。

浏览任何变体的页面时，您可以从左侧的导航栏跳转到其他页面。您可以折叠此导航以仅显示图标。

后续步骤中我们将介绍一些页面，但请随意点击查看每个页面的内容。您还可以展开下面的摘要表。

Studio 中的变体页面

4. 配置您的路由器的网络设置

在我们尝试执行您超级图的操作之前，我们需要确保您的路由器已设置好，能够成功与您的客户端和子图进行通信。

从左侧导航中打开您变体的Cloud Router页面。此页面显示您路由器的端点URL，并允许您使用基于YAML的配置自定义其网络行为。路由器配置YAML下，您将看到以下类似默认配置：

1
cors:
2
  origins:
3
    - https://studio.apollographql.com
4
headers:
5
  subgraphs:
6
    locations: # This value matches your subgraph's name.
7
      request:
8
        - propagate:
9
            matching: '.*'

让我们修改此默认配置，使其能够与您的客户端和子图一起工作。

CORS规则

跨源资源共享协议（CORS）允许服务器精确指定从浏览器可以与其通信的源。

如上配置所示，默认情况下，您的路由器仅接受从GraphOS Studio发出的基于浏览器的请求！如果其他基于浏览器的应用程序将查询您的超级图，您需要修改您的CORS设置。

为了限制基于浏览器的查询仅针对特定域名，请在配置YAML文件中列出这些域名，如下所示：

1
cors:
2
  origins:
3
    - https://studio.apollographql.com
4
    - https://first-domain.example.com
5
    - https://second-domain.example.com

要允许任何域的原生前端查询，您可以替换为以下设置：allow_any_origin: true：

1
cors:
2
  allow_any_origin: true

头部规则

如果您的子图的服务器需要某些HTTP头部才能与其通信（例如，一个Authorization头部），请让我们在配置YAML中指定这些头部。

创建秘密

如果任何必需的头部值包含一个安全凭证（例如访问令牌），让我们首先为该凭证创建一个router特定的秘密。

在云路由器页面上，单击保存秘密。出现以下对话框：

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

您的秘密已加密并存储。现在您可以在router的配置YAML中使用秘密的值。

设置头部值

在您的配置YAML中，您可以这样设置头部值，将其从router传递到您的子图：

1
headers:
2
  subgraphs:
3
    locations: # This value matches your subgraph's name.
4
      request:
5
        - propagate:
6
            matching: '.*'
7
        - insert:
8
            name: 'Authorization'
9
            value: 'Bearer ${env.MY_SECRET}'
10
        - insert:
11
            name: 'X-CUSTOM-HEADER'
12
            value: 'Custom value'

在这里，我们添加了两个头部： Authorization和X-CUSTOM-HEADER。 Authorization头部的值包括一个命名为MY_SECRET的router-specific secret的值。

5. 查询您的超级图

让我们尝试执行对您新创建的超级图的查询！为此，我们将使用工作室最强大的功能之一：探索者。探索者是一个GraphQL IDE，它提供了对您超级图完整模式的可见性，并帮助您构建和运行针对它的查询。

从您组织的图标签页中，选择您的新变体，然后从左侧导航打开其探索者页面。

尝试构建一些查询并在您的超级图上运行它们。请注意，超级图支持与您的底层GraphQL API完全相同的查询结构。

因为您已创建云超级图，探索者中运行的操作将发送到您的API前面的GraphOS Router。应用客户端也将查询router而不是直接查询API。

ⓘ 注

如果探索者返回所有操作的错误，GraphOS可能尚未完成为Router的配置。如果是这种情况，页面上方将显示INITIATING ENDPOINT标签：

6. 查看操作和字段指标

云supergraph的一个强大优点是：因为客户端在你的GraphOS Router上执行操作，所以该路由器会自动收集这些操作以及它们的字段的指标。您可以在工作室中可视化这些指标。

转到您变体's 洞察页面，其外观如下：

您在探索器中执行的操作应已经在此页面上表示。在您将所有客户端更新为查询您的路由器后，洞察页面对于监视supergraph's性能变得至关重要。

有关可用的指标的更多信息，请参阅指标文档。

7. 连接客户端到您的路由器

您的supergraph已准备好开始接收客户端操作！如果您有现有的直接连接到您的GraphQL API的客户端应用程序，您可以更新它们的GraphQL端点URL到您的路由器的URL。

同样，任何新的客户端应用程序都应该使用您的路由器的URL。

您路由器的URL可在变体的 graph ref页面的顶部直接获取，位于变体的graph ref下。

下一步操作

恭喜您！🎉 您已在GraphOS上构建了您的第一个云supergraph。接下来，我们将介绍对您的supergraph执行的一些最常见和最重要的操作，包括

• 更新您的subgraph的schema
• 添加另一个subgraph
• 设置 schema checks

转到下一步。