嵌入探索器

将探索器嵌入您的网站，以赋予您的图消费者更多功能

您可以嵌入GraphOS 工作室探索器到网页中，您可以为您的图消费者提供此网页。这使消费者能够从您的网站测试操作。

例如，这里是一个嵌入的用于 Apollo 示例图的探索器。试试看！

在 Apollo 服务器首页嵌入

在 Apollo Server v3.8.0 以及更晚的版本中，您可以直接使用内置插件将探索器嵌入服务器的主页。

您可以使用ApolloServerPluginLandingPageLocalDefault 插件在本地开发环境中配置主页，并使用 ApolloServerPluginLandingPageProductionDefault 用于生产环境：

1
import {
2
  ApolloServerPluginLandingPageLocalDefault,
3
  ApolloServerPluginLandingPageProductionDefault,
4
} from "@apollo/server/plugin/landingPage/default";
5

6
let plugins = [];
7
if (process.env.NODE_ENV === "production") {
8
  plugins = [ApolloServerPluginLandingPageProductionDefault({ embed: true, graphRef: "myGraph@prod" })];
9
} else {
10
  plugins = [ApolloServerPluginLandingPageLocalDefault({ embed: true })];
11
}
12

13
const server = new ApolloServer({
14
  typeDefs,
15
  resolvers,
16
  plugins,
17
});

更多信息，请参阅主页插件 API 参考。

在任意网页上嵌入

Open GraphOS Studio 并选择要使用嵌入探索器的版本。
转到的探索器页面。
在探索器的设置选项卡下，找到 嵌入探索器 并点击 复制代码段。出现一个包含选项和代码段的对话框。
使用对话框左侧的选项来自定义嵌入探索器外观和行为。
仍然在对话框中，使用上面的选项卡选择您的用例的片段
- 使用 React 用于 React 应用程序，其中您可以 npm install 的 @apollo/explorer。您需要安装可选依赖项 use-deep-compare-effect才能使用 React 包。
- 使用 JavaScript 用于非 React JavaScript 应用程序，其中您可以 npm install的 @apollo/explorer。
- 使用CDN上的构建文件来使用Apollo的CDN托管嵌入式探索器。
点击复制以复制代码段，然后将它粘贴到你的代码中。

ⓘ 注意

有关对话框中显示的选项的说明（以及未显示的选项），请参阅以下内容（以下）。

设置默认操作

您可以从现有的探索器标签中预置您的嵌入式探索器中的一个操作。如果您这样做，加载嵌入式探索器将自动包括以下内容：

您选择的操作
在操作的相关标签中定义，并由操作使用的任何变量名和值
在操作的相关标签中定义的所有头名称和值

要预置默认操作，请使用以下方法之一：

方法1

打开•••旁边的操作菜单，然后点击嵌入此操作：

方法2

在探索器中打开分享下拉菜单，选择嵌入分享：

授权

如果您正在嵌入公开版本，任何人都可以访问嵌入式探索器并查看您的模式以及对您的版本进行查询。

如果您正在嵌入私有的版本，嵌入式探索器首先会要求用户通过在GraphOS Studio中登录进行身份验证。

经过授权后，用户可以访问包含模式导航和可见的操作集合的嵌入式探索器。

选项

嵌入式探索器对象接受一个具有以下结构的选项对象（以下将描述各个选项）：

1
{
2
  graphRef: 'acephei@current',
3
  endpointUrl: 'https://acephei-gateway.herokuapp.com',
4
  persistExplorerState: false,
5
  initialState: {
6
    document: `query ExampleQuery {
7
  me {
8
    id
9
  }
10
}
11
`,
12
    variables: { 'Variable1': 'ExampleValue' },
13
    headers: { 'Header1': 'ExampleValue' },
14
    displayOptions: {
15
      showHeadersAndEnvVars: true,
16
      docsPanelState: 'open',
17
      theme: 'light',
18
    },
19
  },
20
  handleRequest: (endpointUrl, options) => {
21
    return fetch(endpointUrl, {
22
      ...options,
23
      headers: {
24
          ...options.headers,
25
          authorization: `token ${token}`
26
      },
27
    })
28
  },
29
}

顶级选项

这些是您可以包括在传递给new EmbeddedExplorer的选项对象中的顶级字段

名称类型	描述
`graphRef` `字符串`	必需。您想要与嵌入式探索器一起使用的graph ref。其格式为`graph-id@variant-name`。此值将在探索器的嵌入代码段中自动填充。探索器从GraphOS Studio获取此版本的模式，以填充其文档面板并启用代码完成。如果您省略此选项，探索器仍然可以加载，但它不知道要获取哪个模式。这会阻止探索器提供文档和代码完成等重要功能。
`endpointUrl` `字符串`	您想要使用嵌入式探索器与之一起使用的版本的端点URL。此值将在探索器的嵌入代码段中自动填充。必需，除非您使用`handleRequest`选项指定自己的fetcher。
`autoInviteOptions` `{ accountId: string; inviteToken: string; }`	如果您要嵌入的graph是一个私有版本，我们默认仅允许您组织的成员查看嵌入的探索器。您可以使用此配置对象指定访问您嵌入的探索器的任何人都会自动被邀请加入您的组织。当您从Studio中的探索器设置获取嵌入代码时，您可以选择邀请人员应担任的角色，并且`inviteToken`和`accountId`将自动填写。如果您要嵌入的graph属于SSO组织，人们将能够使用SSO账户登录并自动以在Studio中“组织设置”页面上指定的角色被邀请。向属于SSO账户的图形嵌入配置传递此选项不会更改任何行为。新加入您组织的用户始终将被邀请为在Studio中的“组织设置”页面上指定的角色。
`persistExplorerState` `true \| false`	如果`true`，嵌入的探索器使用`localStorage`来持久化其状态（包括operations、标签页、变量和头信息）。如果`false`，嵌入的探索器将加载一个基于您架构的示例查询（除非您提供`document`）。默认值是`false`。
`handleRequest` `(url, options) => Promise`	默认情况下，嵌入的探索器使用`fetch`API将请求发送到您的`endpointUrl`。您可以传递一个自定义的fetcher来运行所有operations。您可能需要这样做，如果您需要在来自嵌入的探索器的每个请求中包含特定的头信息。
`includeCookies` `布尔型`	默认情况下，嵌入的探索器使用您变体的包含Cookies设置，您可以从非嵌入的探索器在Studio中进行配置。您可以将`includeCookies`设置为`true`，如果希望探索器将其请求的`{ credentials: 'include' }`传递。如果传递了`handleRequest`选项，则忽略此选项。有关`fetch`API和凭证的更多信息，请参见此处。此配置选项已被弃用，建议您在非嵌入式浏览器的包含cookie设置中配置您变体的
`initialState` `对象`	一个对象，包含与页面加载时嵌入式浏览器状态相关的附加选项。有关支持的子字段，请参见`initialState` 选项。

`initialState` 选项

以下是在您传递给new EmbeddedExplorer的initialState选项中可以包含的字段：

名称类型	描述
`document` `字符串`	一个用于在嵌入式浏览器编辑器上加载的URI编码操作。如果您省略此选项，浏览器最初将加载一个基于您模式的示例查询。如果您使用设置默认操作中描述的共享方法之一，生成的代码片段将自动使用您使用的操作的详细信息设置此选项。如果`persistExplorerState`设置为`true`，并且您提供了此选项，则浏览器将加载用户的任何选项卡从`localStorage`，并且它还将打开一个新的选项卡以执行此操作。示例 intialState: { document: ` query ExampleQuery { books { title } } `; }
`variables` `字符串`	一个包含初始变量值的URI编码、序列化对象，用于在加载时填充到浏览器中。如果提供，这些变量应适用于您为`document`提供的初始示例 intialState: { variables: { userID: "abc123" }, }
`headers` `字符串`	一个包含初始HTTP标头值的URI编码、序列化对象，用于在加载时填充到浏览器中。示例 initialState: { headers: { authorization: "Bearer abc123"; } }
`collectionId` / `operationId` `字符串`	这是要填充到浏览器中的集合 ID，与操作 ID 配对。您可以在...菜单下一步骤操作旁边点击并选择查看操作详情以找到这些值。示例 initialState: { collectionId: 'abc1234', operationId: 'xyz1234' }

`displayOptions` 选项

以下是在您传递给new EmbeddedExplorer的initialState.displayOptions选项中可以包含的字段：

名称类型	描述
`docsPanelState` `"open" \| "closed"`	如果为`open`，则浏览器文档面板（左侧栏）最初展开。如果为`closed`，则面板最初折叠。默认值为`open`。
`showHeadersAndEnvVars` `true \| false`	如果为`true`，则嵌入式浏览器包括设置请求标头和环境变量的面板。如果为`false`，则那些面板不存在。默认值为`true`。
`theme` `"dark" \| "light"`	如果 `dark`，则使用浏览器的深色主题。如果 `light`，则使用浅色主题。默认值是 `dark`。

名称类型	描述
`graphRef` `字符串`	必需。您想要与嵌入式探索器一起使用的graph ref。其格式为`graph-id@variant-name`。此值将在探索器的嵌入代码段中自动填充。探索器从GraphOS Studio获取此版本的模式，以填充其文档面板并启用代码完成。如果您省略此选项，探索器仍然可以加载，但它不知道要获取哪个模式。这会阻止探索器提供文档和代码完成等重要功能。
`endpointUrl` `字符串`	您想要使用嵌入式探索器与之一起使用的版本的端点URL。此值将在探索器的嵌入代码段中自动填充。必需，除非您使用`handleRequest`选项指定自己的fetcher。
`autoInviteOptions` `{ accountId: string; inviteToken: string; }`	如果您要嵌入的graph是一个私有版本，我们默认仅允许您组织的成员查看嵌入的探索器。您可以使用此配置对象指定访问您嵌入的探索器的任何人都会自动被邀请加入您的组织。当您从Studio中的探索器设置获取嵌入代码时，您可以选择邀请人员应担任的角色，并且`inviteToken`和`accountId`将自动填写。如果您要嵌入的graph属于SSO组织，人们将能够使用SSO账户登录并自动以在Studio中“组织设置”页面上指定的角色被邀请。向属于SSO账户的图形嵌入配置传递此选项不会更改任何行为。新加入您组织的用户始终将被邀请为在Studio中的“组织设置”页面上指定的角色。
`persistExplorerState` `true \| false`	如果`true`，嵌入的探索器使用`localStorage`来持久化其状态（包括operations、标签页、变量和头信息）。如果`false`，嵌入的探索器将加载一个基于您架构的示例查询（除非您提供`document`）。默认值是`false`。
`handleRequest` `(url, options) => Promise`	默认情况下，嵌入的探索器使用`fetch`API将请求发送到您的`endpointUrl`。您可以传递一个自定义的fetcher来运行所有operations。您可能需要这样做，如果您需要在来自嵌入的探索器的每个请求中包含特定的头信息。
`includeCookies` `布尔型`	默认情况下，嵌入的探索器使用您变体的包含Cookies设置，您可以从非嵌入的探索器在Studio中进行配置。您可以将`includeCookies`设置为`true`，如果希望探索器将其请求的`{ credentials: 'include' }`传递。如果传递了`handleRequest`选项，则忽略此选项。有关`fetch`API和凭证的更多信息，请参见此处。此配置选项已被弃用，建议您在非嵌入式浏览器的包含cookie设置中配置您变体的
`initialState` `对象`	一个对象，包含与页面加载时嵌入式浏览器状态相关的附加选项。有关支持的子字段，请参见`initialState` 选项。

名称类型	描述
`docsPanelState` `"open" \| "closed"`	如果为`open`，则浏览器文档面板（左侧栏）最初展开。如果为`closed`，则面板最初折叠。默认值为`open`。
`showHeadersAndEnvVars` `true \| false`	如果为`true`，则嵌入式浏览器包括设置请求标头和环境变量的面板。如果为`false`，则那些面板不存在。默认值为`true`。
`theme` `"dark" \| "light"`	如果 `dark`，则使用浏览器的深色主题。如果 `light`，则使用浅色主题。默认值是 `dark`。

嵌入探索器

将探索器嵌入您的网站，以赋予您的图消费者更多功能

在 Apollo 服务器首页嵌入

在任意网页上嵌入

设置默认操作

方法1

方法2

授权

选项

顶级选项

`graphRef`

`endpointUrl`

`autoInviteOptions`

`persistExplorerState`

`handleRequest`

`includeCookies`

`initialState`

`initialState` 选项

`document`

`variables`

`headers`

`collectionId` / `operationId`

`displayOptions` 选项

`docsPanelState`

`showHeadersAndEnvVars`

`theme`