GraphQL 与 Aura Console

这是 GraphQL Library 7 版本的文档。对于长期支持 (LTS) 版本 5，请参考 GraphQL Library 5 LTS 版本。

本教程向您展示如何在 Aura 控制台中创建和使用 GraphQL 数据 API。

先决条件

设置一个 AuraDB 实例。请参考创建 Neo4j Aura 实例。

创建 GraphQL 数据 API

在 Aura 控制台中，从左侧导航栏选择 Data services（数据服务）> Data APIs（数据 API），然后点击 Create API（创建 API）。

详细信息

在 Details（详细信息）下，为您的新 API 提供一个名称以及您要使用的实例数据。同时，为了配合 Apollo Server 使用，请勾选 Enable introspection（启用内省）和 Enable field suggestions（启用字段建议）。

如果您在生产系统中设置了 Enable introspection（启用内省）和 Enable field suggestions（启用字段建议），它们提供的信息可能会被恶意攻击者用于逆向工程您的 GraphQL 架构并执行任意操作。

Enable introspection（启用内省）允许您查询架构并发现 GraphQL API 中可用的查询、变更、订阅、类型和字段。

Enable field suggestions（启用字段建议）提供针对 GraphQL 拼写错误的提示。即使仅启用了字段建议，恶意攻击者也有可能发现您的整个架构。

类型定义

粘贴这些 Type definitions（类型定义）

type Product @node {
    productName: String
    category: [Category!]! @relationship(type: "PART_OF", direction: OUT)
}

type Category @node {
    categoryName: String
    products: [Product!]! @relationship(type: "PART_OF", direction: IN)
}

类型定义描述了 AuraDB 中图形数据库的哪些部分可以通过 GraphQL API 发出的请求进行访问。

或者，如果您已经在 AuraDB 中拥有数据，可以通过 Neo4j GraphQL Toolbox 获取您的类型定义。该工具箱可以连接到 AuraDB 并自动创建类型定义，从而允许进行 GraphQL 操作。

如果您正在使用 GraphQL Federation，请确保选中 Enable GraphQL subgraph（启用 GraphQL 子图）。

跨域资源共享 (CORS) 策略

要将您的 GraphQL API 与基于浏览器的应用程序结合使用，请在您的跨域资源共享 (CORS) 策略中添加一个条目。CORS 是一种基于浏览器的安全机制，可防止网页访问来自不同源的服务器资源。

将 URL https://studio.apollographql.com 添加到 Origin（源）框中，以启用 Apollo Studio 的使用。如果您需要更多条目，请为它们点击 Add allowed origin（添加允许的源）。

CORS 策略中输入的 URL 必须完全匹配。不支持通配符。

身份验证提供程序

所有对 GraphQL API 的请求都经过身份验证，身份验证类型有两种选项：API 密钥或 JSON Web 密钥集 (JWKS)。可以设置多个身份验证提供程序，并为每个请求选择不同的提供程序。

在本教程中，请避免设置 JWKS 端点，从下拉列表中选择 API Key（API 密钥）并输入名称。GraphQL API 密钥创建后，该密钥将会显示。

不建议将 API 密钥用于使用 GraphQL API 的面向用户的应用程序。这是因为 API 密钥存在被恶意用户看到的风险，且对 GraphQL 操作的控制非常有限。

带有 JWKS 的第三方身份提供程序可提供更好的安全性，并允许根据 JWKS 令牌中的信息定义细粒度的安全规则（在类型定义内），从而控制 GraphQL 操作。

规格大小

GraphQL API 的规格大小取决于类型定义的规模和复杂性以及预期的工作负载。更大的规格每小时成本更高。如果未显示成本，请参考您与 Neo4j 签署的协议。

API 密钥

Create（创建）GraphQL API。

您的 API 密钥现已显示。请妥善保存此信息，因为它无法再次检索。确认点击 I understand（我已了解）和 Close（关闭）。

GraphQL API 将开始部署。您可以通过左侧导航栏的 Data APIs 查看状态。

在数据库中创建节点

当 GraphQL API 的状态为 Ready（就绪）时，您可以向其发送 GraphQL 请求。

通过 cURL

curl --location <YOUR_GRAPHQL_API_URL> --header 'Content-Type: application/json' --header 'x-api-key: <YOUR_API_KEY>' --data '{ "query": "<YOUR_GRAPHQL_QUERY>" }'

在命令行中，执行

curl --location <YOUR_GRAPHQL_API_URL> --header 'Content-Type: application/json' --header 'x-api-key: <YOUR_API_KEY>' --data '{ "query": "mutation { createProducts( input: [ { productName: \"New Product\" category: { create: [ { node: { categoryName: \"New Category\" } } ] } } ] ) { products { productName category { categoryName } } } }" }'

通过查询您刚刚添加的数据进行验证

curl --location <YOUR_GRAPHQL_API_URL> --header 'Content-Type: application/json' --header 'x-api-key: <YOUR_API_KEY>' --data '{ "query": "query { products { productName category { categoryName } } }" }'

您应该会看到以下内容

{ "data": { "products": [ { "productName": "New Product", "category": [{ "categoryName": "New Category" }] } ] } }

通过 Apollo Server

在 Apollo Studio 网站上，将您的 GraphQL 数据 API URL 粘贴到 Sandbox（沙盒）输入框中。
使用齿轮图标，在 Shared headers（共享标头）下添加 x-api-key 和您的数据 API 的 API 密钥，然后点击 Save（保存）。

要开始添加数据，请复制并将以下变更 (mutation) 粘贴到 Operation（操作）面板中，以创建一个产品及其分类

mutation {
  createProducts(
    input: [
      {
        productName: "New Product"
        category: { create: [{ node: { categoryName: "New Category" } }] }
      }
    ]
  ) {
    products {
      productName
      category {
        categoryName
      }
    }
  }
}

点击右上角的 Run（运行）。您应该会在 Response（响应）面板中看到数据已在数据库中创建的确认信息

{
  "data": {
    "createProducts": {
      "products": [
        {
          "productName": "New Product",
          "category": [
            {
              "categoryName": "New Category"
            }
          ]
        }
      ]
    }
  }
}

查询您刚刚添加的数据。复制并将以下查询粘贴到 Operations（操作）面板中

query {
  products {
    productName
    category {
      categoryName
    }
  }
}

由于您只创建了一个“Product”节点和一个“Category”节点，Response（响应）面板将显示以下内容

{
  "data": {
    "products": [
      {
        "productName": "New Product",
        "category": [
          {
            "categoryName": "New Category"
          }
        ]
      }
    ]
  }
}

本教程到此结束。您现在已经拥有一个连接到 Neo4j AuraDB 的 GraphQL 数据 API，并添加了两个节点。

要了解更多信息，请参阅查询与聚合和 Neo4j GraphQL 工具箱。有关更高级的数据库设置，请参考驱动程序配置。