本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 适用于 GraphQL 的 Amazon Neptune 实用程序 适用于 [GraphQL](https://graphql.org/) 的 Amazon Neptune 实用程序是一款开源 Node.js 命令行工具，可以帮助您为 Neptune 属性图形数据库创建和维护 GraphQL API（它尚未处理 RDF 数据）。对于具有可变数量的输入参数并返回可变数量的嵌套字段的 GraphQL 查询，这是一种创建 GraphQL 解析器的无代码方法。 它已作为开源项目发布，位于[https://github.com/aws/amazon-neptune-for-graphql](https://github.com/aws/amazon-neptune-for-graphql)。 您可以像这样使用 NPM 来安装该实用程序（有关详细信息，请参阅[安装和设置](tools-graphql-setup.md)）： ``` npm i @aws/neptune-for-graphql -g ``` 该实用程序可以发现现有 Neptune 属性图的图形架构，包括节点、边缘、属性和边缘基数。然后，它生成一个 GraphQL 架构，其中包含将 GraphQL 类型映射到节点和数据库边缘所需的指令，并自动生成解析器代码。解析器代码旨在通过仅返回由 GraphQL 查询请求的数据来最大限度地减少延迟。 也可以从现有的 GraphQL 架构和空的 Neptune 数据库开始，然后让该实用程序推理所需的指令，以便将该 GraphQL 架构映射到要加载到数据库中的数据的节点和边缘。或者，您可以从已经创建或修改的 GraphQL 架构和指令开始。 该实用程序能够创建其管道所需的所有 AWS 资源，包括 AWS AppSync API、IAM 角色、数据源、架构和解析器，以及查询 Neptune 的 Lamb AWS da 函数。 **注意** 此处的命令行示例假设使用 Linux 控制台。如果使用的是 Windows，请将行末尾的反斜杠 ('\$1') 替换为插入符号 ('^')。 **Topics** + [安装和设置适用于 GraphQL 的 Amazon Neptune 实用程序](tools-graphql-setup.md) + [扫描现有 Neptune 数据库中的数据](tools-graphql-scan-existing.md) + [从没有指令的 GraphQL 架构开始](tools-graphql-start-from-schema.md) + [使用 GraphQL 架构的指令](tools-graphql-schema-with-directives.md) + [GraphQL 实用程序的命令行参数](tools-graphql-cmd-line-args.md) # 安装和设置适用于 GraphQL 的 Amazon Neptune 实用程序 如果要将该实用程序与现有 Neptune 数据库一起使用，则需要它才能连接到数据库端点。默认情况下，只能从 Neptune 数据库所在的 VPC 内访问该数据库。 由于该实用程序是 Node.js 命令行工具，因此必须安装 Node.js（版本 18 或更高版本）才能运行该实用程序。要在与 Neptune 数据库相同的 EC2 实例上安装 Node.js，请按照[此处的说明](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-up-node-on-ec2-instance.html)操作。运行该实用程序的最小大小实例为 t2.micro。在创建实例期间，从**常见安全组**下拉菜单中选择 Neptune 数据库 VPC。 要在 EC2 实例或本地计算机上安装实用程序本身，请使用 NPM： ``` npm i @aws/neptune-for-graphql -g ``` 然后，您可以运行该实用程序的 help 命令来检查它安装是否正确： ``` neptune-for-graphql --help ``` 您可能还需要[安装 AWS CLI来](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)管理 AWS 资源。 # 扫描现有 Neptune 数据库中的数据 无论您是否熟悉 GraphQL，下面的命令都是创建 GraphQL API 的最快方法。这假设您已按照[安装部分](tools-graphql-setup.md)所述安装并配置了适用于 GraphQL 的 Neptune 实用程序，以便它连接到您的 Neptune 数据库的端点。 ``` neptune-for-graphql \ --input-graphdb-schema-neptune-endpoint (your neptune database endpoint):(port number) \ --create-update-aws-pipeline \ --create-update-aws-pipeline-name (your new GraphQL API name) \ --output-resolver-query-https ``` 该实用程序分析数据库以发现其中的节点、边缘和属性的架构。根据该架构，它推理带有关联查询和突变的 GraphQL 架构。然后，它会创建一个 AppSync GraphQL API 以及使用它所需的 AWS 资源。这些资源包括一对 IAM 角色和一个包含 GraphQL 解析器代码的 Lambda 函数。 该实用程序完成后，您将在 AppSync控制台中找到一个新的 GraphQL API，名称与您在命令中分配的名称相同。要对其进行测试，请使用菜单上的 “ AppSync **查询**” 选项。 如果您在向数据库添加更多数据后再次运行相同的命令，则会相应地更新 AppSync API 和 Lambda 代码。 要释放与该命令关联的所有资源，请运行： ``` neptune-for-graphql \ --remove-aws-pipeline-name (your new GraphQL API name from above) ``` # 从没有指令的 GraphQL 架构开始 您可以从空的 Neptune 数据库开始，使用没有指令的 GraphQL 架构来创建数据并进行查询。以下命令会自动创建 AWS 资源来执行此操作： ``` neptune-for-graphql \ --input-schema-file (your GraphQL schema file) --create-update-aws-pipeline \ --create-update-aws-pipeline-name (name for your new GraphQL API) \ --create-update-aws-pipeline-neptune-endpoint (your Neptune database endpoint):(port number) \ --output-resolver-query-https ``` GraphQL 架构文件必须包含 GraphQL 架构类型，如下面的 TODO 示例所示。该实用程序会分析您的架构，并根据您的类型创建扩展版本。它为存储在图形数据库中的节点添加查询和突变，如果您的架构具有嵌套类型，则它会添加作为边缘存储在数据库中的类型之间的关系。 该实用程序创建了一个 AppSync GraphQL API 以及所需的所有 AWS 资源。其中包括一对 IAM 角色和一个包含 GraphQL 解析器代码的 Lambda 函数。命令完成后，您可以使用您在控制台中指定的名称找到一个新的 GraphQL API。 AppSync 要对其进行测试，请在 AppSync 菜单中使用**查询**。 以下示例说明了其工作原理： ## Todo 示例，从没有指令的 GraphQL 架构开始 在这个例子中，我们从一个没有指令的 Todo GraphQL 架构开始，你可以在目录中*???samples???*找到该架构。它包括以下两种类型： ``` type Todo { name: String description: String priority: Int status: String comments: [Comment] } type Comment { content: String } ``` 此命令处理待办事项架构和空的 Neptune 数据库的端点，以便在以下位置创建 GraphQL API： AWS AppSync ``` neptune-for-graphql / --input-schema-file ./samples/todo.schema.graphql \ --create-update-aws-pipeline \ --create-update-aws-pipeline-name TodoExample \ --create-update-aws-pipeline-neptune-endpoint (empty Neptune database endpoint):(port number) \ --output-resolver-query-https ``` 该实用程序在名为的输出文件夹中创建一个新文件`TodoExample.source.graphql`，并在中创建 GraphQL API。 AppSync该实用程序推理以下内容： + 在待办事项类型中，它`@relationship`为一种新 CommentEdge 类型添加了。这指示解析器使用名为的图形数据库边缘将 Todo 连接到 Comment。 CommentEdge + 它添加了一个名 TodoInput 为帮助查询和变更的新输入。 + 它为每种类型（Todo、Comment）添加了两个查询：一个查询用于使用输入中列出的一个 `id` 或任何一个类型字段检索单个类型，另一个查询用于检索使用该类型的输入进行筛选的多个值。 + 它为每种类型添加了三个突变：创建、更新和删除。要删除的类型是使用 `id` 或该类型的输入来指定的。这些突变会影响存储在 Neptune 数据库中的数据。 + 它为连接添加了两个突变：连接和删除。它们将 Neptune 使用的起始顶点和结束顶点的节点 ID 作为输入，连接是数据库中的边缘。 解析器通过名称识别查询和突变，但您可以按[如下](tools.md)所示对其进行自定义。 以下是 `TodoExample.source.graphql` 文件的内容： ``` type Todo { _id: ID! @id name: String description: String priority: Int status: String comments(filter: CommentInput, options: Options): [Comment] @relationship(type: "CommentEdge", direction: OUT) bestComment: Comment @relationship(type: "CommentEdge", direction: OUT) commentEdge: CommentEdge } type Comment { _id: ID! @id content: String } input Options { limit: Int } input TodoInput { _id: ID @id name: String description: String priority: Int status: String } type CommentEdge { _id: ID! @id } input CommentInput { _id: ID @id content: String } input Options { limit: Int } type Query { getNodeTodo(filter: TodoInput, options: Options): Todo getNodeTodos(filter: TodoInput): [Todo] getNodeComment(filter: CommentInput, options: Options): Comment getNodeComments(filter: CommentInput): [Comment] } type Mutation { createNodeTodo(input: TodoInput!): Todo updateNodeTodo(input: TodoInput!): Todo deleteNodeTodo(_id: ID!): Boolean connectNodeTodoToNodeCommentEdgeCommentEdge(from_id: ID!, to_id: ID!): CommentEdge deleteEdgeCommentEdgeFromTodoToComment(from_id: ID!, to_id: ID!): Boolean createNodeComment(input: CommentInput!): Comment updateNodeComment(input: CommentInput!): Comment deleteNodeComment(_id: ID!): Boolean } schema { query: Query mutation: Mutation } ``` 现在，您可以创建和查询数据。**以下是用于测试新 GraphQL API 的 Queries 控制台的快照，在本例`TodoExampleAPI`中命名。 AppSync**在中间的窗口中，Explorer 显示查询和突变的列表，您可以从中挑选查询、输入参数和返回字段。此屏幕截图显示了使用 `createNodeTodo` 突变创建 Todo 节点类型的过程： ![\[屏幕截图显示 AppSync Queries 控制台正在创建 Todo 节点\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/images/todoCreate.png) 此屏幕截图显示使用 `getNodeTodos` 查询来查询所有 Todo 节点： ![\[屏幕截图显示 AppSync Queries 控制台正在查询 Todo 节点\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/images/todoGetTodos.png) 使用 `createNodeComment` 创建 Comment（注释）后，您可以使用 `connectNodeTodoToNodeCommentEdgeCommentEdge` 突变通过指定其 ID 来连接它们。以下是检索 Todo 及其所附注释的嵌套查询： ![\[屏幕截图显示了用于在 Queries 控制台中检索 Todo 及其所附评论的嵌套 AppSync 查询\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/images/todoNestedQuery.png) 如果要按照[使用指令](tools-graphql-schema-with-directives.md)中所述对 `TodoExample.source.graphql` 文件进行更改，则可以使用编辑后的架构作为输入并再次运行该实用程序。然后，该实用程序将相应地修改 GraphQL API。 # 使用 GraphQL 架构的指令 您可以从已经有指令的 GraphQL 架构开始，使用如下命令： ``` neptune-for-graphql \ --input-schema-file (your GraphQL schema file with directives) \ --create-update-aws-pipeline \ --create-update-aws-pipeline-name (name for your new GraphQL API) \ --create-update-aws-pipeline-neptune-endpoint (empty Neptune database endpoint):(port number) \ --output-resolver-query-https ``` 您可以修改该实用程序创建的指令，也可以将自己的指令添加到 GraphQL 架构中。以下是一些使用指令的方法： ## 运行该实用程序使其不会生成突变 要防止该实用程序在 GraphQL API 中生成突变，请在 `neptune-for-graphql` 命令中使用 `--output-schema-no-mutations` 选项。 ## `@alias` 指令 `@alias` 指令可以应用于 GraphQL 架构类型或字段。它在图形数据库和 GraphQL 架构之间映射不同的名称。语法如下： ``` @alias(property: (property name)) ``` 在下面的示例中，`airport` 是映射到 `Airport` GraphQL 类型的图形数据库节点标签，`desc` 是映射到 `description` 字段的图形节点属性（请参阅[航线示例](tools-graphql.md)）： ``` type Airport @alias(property: "airport") { city: String description: String @alias(property: "desc") } ``` 请注意，标准 GraphQL 格式要求使用 Pascal 大小写的类型名称和驼峰式大小写的字段名称。 ## `@relationship` 指令 `@relationship` 指令将嵌套的 GraphQL 类型映射到图形数据库边缘。语法如下： ``` @relationship(edgeType: (edge name), direction: (IN or OUT)) ``` 以下是一个示例命令： ``` type Airport @alias(property: "airport") { ... continentContainsIn: Continent @relationship(edgeType: "contains", direction: IN) countryContainsIn: Country @relationship(edgeType: "contains", direction: IN) airportRoutesOut(filter: AirportInput, options: Options): [Airport] @relationship(edgeType: "route", direction: OUT) airportRoutesIn(filter: AirportInput, options: Options): [Airport] @relationship(edgeType: "route", direction: IN) } ``` 您可以在 [TODO 示例](tools-graphql-start-from-schema.md#tools-graphql-todo-example)和[航线示例](tools-graphql.md)中找到 `@relationship` 指令。 ## `@graphQuery` 和 `@cypher` 指令 您可以定义 openCypher 查询来解析字段值、添加查询或添加突变。例如，这将在 `Airport` 类型中添加新的 `outboundRoutesCount` 字段来计算出站路线： ``` type Airport @alias(property: "airport") { ... outboundRoutesCount: Int @graphQuery(statement: "MATCH (this)-[r:route]->(a) RETURN count(r)") } ``` 以下是新查询和突变的示例： ``` type Query { getAirportConnection(fromCode: String!, toCode: String!): Airport \ @cypher(statement: \ "MATCH (:airport{code: '$fromCode'})-[:route]->(this:airport)-[:route]->(:airport{code:'$toCode'})") } type Mutation { createAirport(input: AirportInput!): Airport @graphQuery(statement: "CREATE (this:airport {$input}) RETURN this") addRoute(fromAirportCode:String, toAirportCode:String, dist:Int): Route \ @graphQuery(statement: \ "MATCH (from:airport{code:'$fromAirportCode'}), (to:airport{code:'$toAirportCode'}) \ CREATE (from)-[this:route{dist:$dist}]->(to) \ RETURN this") } ``` 请注意，如果省略 `RETURN`，则解析器会假定关键字 `this` 是返回范围。 也可以使用 Gremlin 查询添加查询或突变： ``` type Query { getAirportWithGremlin(code:String): Airport \ @graphQuery(statement: "g.V().has('airport', 'code', '$code').elementMap()") # single node getAirportsWithGremlin: [Airport] \ @graphQuery(statement: "g.V().hasLabel('airport').elementMap().fold()") # list of nodes getCountriesCount: Int \ @graphQuery(statement: "g.V().hasLabel('country').count()") # scalar } ``` 目前，Gremlin 查询仅限于返回标量值的查询，或 `elementMap()` 对应于单个节点，或 `elementMap().fold()` 对应于节点列表。 ## `@id` 指令 `@id` 指令标识映射到 `id` 图形数据库实体的字段。像 Amazon Neptune 这样的图形数据库对于在批量导入期间分配或自动生成的节点和边缘始终具有唯一的 `id`。例如： ``` type Airport { _id: ID! @id city: String code: String } ``` ## 保留类型、查询和突变名称 该实用程序会自动生成查询和突变以创建可正常运行的 GraphQL API。这些名称的模式被解析器识别并保留。以下是类型 `Airport` 和连接类型 `Route` 的示例： `Options` 类型已保留。 ``` input Options { limit: Int } ``` `filter` 和 `options` 函数参数已保留。 ``` type Query { getNodeAirports(filter: AirportInput, options: Options): [Airport] } ``` 查询名称的 getNode 前缀已保留，诸如 `createNode`、`updateNode`、`deleteNode`、`connectNode`、`deleteNode`、`updateEdge` 和 `deleteEdge` 之类的突变名称的前缀已保留。 ``` type Query { getNodeAirport(id: ID, filter: AirportInput): Airport getNodeAirports(filter: AirportInput): [Airport] } type Mutation { createNodeAirport(input: AirportInput!): Airport updateNodeAirport(id: ID!, input: AirportInput!): Airport deleteNodeAirport(id: ID!): Boolean connectNodeAirportToNodeAirportEdgeRout(from: ID!, to: ID!, edge: RouteInput!): Route updateEdgeRouteFromAirportToAirport(from: ID!, to: ID!, edge: RouteInput!): Route deleteEdgeRouteFromAirportToAirport(from: ID!, to: ID!): Boolean } ``` ## 将更改应用于 GraphQL 架构 您可以修改 GraphQL 源架构并再次运行该实用程序，从 Neptune 数据库中获取最新架构。每当该实用程序在数据库中发现新架构时，它都会生成一个新的 GraphQL 架构。 您也可以手动编辑 GraphQL 源架构，然后使用源架构而不是 Neptune 数据库端点作为输入再次运行该实用程序。 最后，您可以使用以下 JSON 格式将更改放入文件中： ``` [ { "type": "(GraphQL type name)", "field": "(GraphQL field name)", "action": "(remove or add)", "value": "(value)" } ] ``` 例如： ``` [ { "type": "Airport", "field": "outboundRoutesCountAdd", "action": "add", "value":"outboundRoutesCountAdd: Int @graphQuery(statement: \"MATCH (this)-[r:route]->(a) RETURN count(r)\")" }, { "type": "Mutation", "field": "deleteNodeVersion", "action": "remove", "value": "" }, { "type": "Mutation", "field": "createNodeVersion", "action": "remove", "value": "" } ] ``` 然后，当您在命令中使用 `--input-schema-changes-file` 参数对此文件运行该实用程序时，该实用程序会立即应用您的更改。 # GraphQL 实用程序的命令行参数 + **`--help, -h`** – 将 GraphQL 实用程序的帮助文本返回到控制台。   + **`--input-schema (schema text)`** – 要用作输入的 GraphQL 架构，带或不带指令。   + **`--input-schema-file (file URL)`** – 包含要用作输入的 GraphQL 架构的文件的 URL。   + **`--input-schema-changes-file (file URL)`** – 包含要对 GraphQL 架构所做的更改的文件的 URL。如果您多次对 Neptune 数据库运行该实用程序，并且还手动更改 GraphQL 源架构（可能添加自定义查询），则手动更改将丢失。为避免这种情况，请将您的更改放在更改文件中，然后使用此参数将其传入。 更改文件采用以下 JSON 格式： ``` [ { "type": "(GraphQL type name)", "field": "(GraphQL field name)", "action": "(remove or add)", "value": "(value)" } ] ``` 有关更多信息，请参阅 [Todo 示例](tools-graphql-start-from-schema.md#tools-graphql-todo-example)。   + **`--input-graphdb-schema (schema text)`** – 您可以用文本形式表达 graphdb 架构以用作输入，而不是对 Neptune 数据库运行该实用程序。graphdb 架构具有如下所示的 JSON 格式： ``` { "nodeStructures": [ { "label":"nodelabel1", "properties": [ { "name":"name1", "type":"type1" } ] }, { "label":"nodelabel2", "properties": [ { "name":"name2", "type":"type1" } ] } ], "edgeStructures": [ { "label":"label1", "directions": [ { "from":"nodelabel1", "to":"nodelabel2", "relationship":"ONE-ONE|ONE-MANY|MANY-MANY" } ], "properties": [ { "name":"name1", "type":"type1" } ] } ] } ```   + **`--input-graphdb-schema-file (file URL)`** – 您可以将 graphdb 架构保存在文件中以用作输入，而不是对 Neptune 数据库运行该实用程序。有关 graphdb 架构文件的 JSON 格式示例，请参阅上面的 `--input-graphdb-schema`。   + **`--input-graphdb-schema-neptune-endpoint (endpoint URL)`** – Neptune 数据库端点，实用程序应从中提取 graphdb 架构。   + **`--output-schema-file (file name)`** – GraphQL 架构的输出文件名。如果未指定，则默认值为 `output.schema.graphql`，除非使用 `--create-update-aws-pipeline-name` 设置了管道名称，在这种情况下，默认文件名为 `(pipline name).schema.graphql`。   + **`--output-source-schema-file (file name)`** – 带有指令的 GraphQL 架构的输出文件名。如果未指定，则默认值为 `output.source.schema.graphql`，除非使用 `--create-update-aws-pipeline-name` 设置了管道名称，在这种情况下，默认名称为 `(pipeline name).source.schema.graphql`。   + **`--output-schema-no-mutations`** – 如果存在此参数，则该实用程序不会在 GraphQL API 中生成任何突变，只生成查询。   + **`--output-neptune-schema-file (file name)`** – 实用程序发现的 Neptune graphdb 架构的输出文件名。如果未指定，则默认值为 `output.graphdb.json`，除非使用 `--create-update-aws-pipeline-name` 设置了管道名称，在这种情况下，默认文件名为 `(pipeline name).graphdb.json`。   + **`--output-js-resolver-file (file name)`** – 解析器代码副本的输出文件名。如果未指定，则默认值为 `output.resolver.graphql.js`，除非使用 `--create-update-aws-pipeline-name` 设置了管道名称，在这种情况下，文件名为 `(pipeline name).resolver.graphql.js`。 此文件压缩在上传到运行解析器的 Lambda 函数的代码包中。   + **`--output-resolver-query-sdk`** – 此参数指定该实用程序的 Lambda 函数应使用 Neptune 数据 SDK 来查询 Neptune，该 SDK 从 Neptune [引擎版本 1.2.1.0.R5](engine-releases-1.2.1.0.R5.md)（这是默认版本）开始推出。但是，如果该实用程序检测到较旧的 Neptune 引擎版本，则它建议改用 HTTPS Lambda 选项，您可以使用 `--output-resolver-query-https` 参数调用该选项。   + **`--output-resolver-query-https`** – 此参数指定该实用程序的 Lambda 函数应使用 Neptune HTTPS API 查询 Neptune。   + **`--create-update-aws-pipeline`**— 此参数会触发创建供 GraphQL API 使用的 AWS 资源，包括 GraphQL API 和运行 AppSync 解析器的 Lambda。   + **`--create-update-aws-pipeline-name (pipeline name)`**— 此参数设置管道的名称，例如 Lambda `pipeline-name` 函数`pipeline-name`的 API AppSync 或函数。如果未指定名称，则 `--create-update-aws-pipeline` 使用 `Neptune ` 数据库名称。 + **`--create-update-aws-pipeline-region (AWS region)`**— 此参数设置了创 AWS 建 GraphQL API 管道的区域。如果未指定，则默认区域为 `us-east-1` 或 Neptune 数据库所在区域（从数据库端点提取）。 + **`--create-update-aws-pipeline-neptune-endpoint (endpoint URL)`** – 此参数设置 Lambda 函数用于查询数据库的 Neptune 数据库端点。如果未设置，则使用由 `--input-graphdb-schema-neptune-endpoint` 设置的端点。 + **`--remove-aws-pipeline-name (pipeline name)`** – 此参数移除使用 `--create-update-aws-pipeline` 创建的管道。要删除的资源列在名为 `(pipeline name).resources.json` 的文件中。 + **`--output-aws-pipeline-cdk`**— 此参数会触发一个 CDK 文件的创建，该文件可用于为 GraphQL API 创建 AWS 资源，包括 GraphQL API 和运行解析器的 Lambda 函数。 AppSync + **`--output-aws-pipeline-cdk-neptume-endpoint (endpoint URL)`** – 此参数设置 Lambda 函数用于查询 Neptune 数据库的 Neptune 数据库端点。如果未设置，则使用由 `--input-graphdb-schema-neptune-endpoint` 设置的端点。 + **`--output-aws-pipeline-cdk-name (pipeline name)`**— 此参数设置要使用的 AppSync API 和 Lambda 管道名称函数的管道名称。如果未指定，则 `--create-update-aws-pipeline` 使用 Neptune 数据库名称。 + **`--output-aws-pipeline-cdk-region (AWS region)`**— 这将设置创建 GraphQL API 管道的 AWS 区域。如果未指定，则它默认为 `us-east-1` 或 Neptune 数据库所在的区域（从数据库端点提取）。 + **`--output-aws-pipeline-cdk-file (file name)`** – 这将设置 CDK 文件名。如果未设置，则默认为 `(pipeline name)-cdk.js`。