GraphQL API 概述

Archie Core 中的每个项目都使用统一的 API 端点。这个单一端点处理每个数据表的 GraphQL 查询、变更和订阅。API 预配置了过滤、分页、全文搜索和其他高级功能。

所有 API 请求都发送到以下 URL：

https://archie-core.services.archie.com/graphql

要将请求路由到您的特定项目，必须在每个 HTTP 请求中包含包含项目 ID 的 x-project-id 标头。

alt text

理解字段

GraphQL 是用于请求对象上字段的规范。这是一个简单的 Archie Core 查询，它通过唯一的 id 查找特定城市，并请求返回 nameCity 和 state 字段。

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

结果如下：

{
  "data": {
    "citiesById": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago",
      "state": "Illinois"
    }
  }
}

结果与查询具有相同的形状。这是 GraphQL 的关键：您总是得到您请求的内容，服务器知道客户端正在请求哪些字段。

Archie Core GraphQL 查询是交互式的，并且原生支持关系查询。这意味着两件重要的事情：

查询可以随时更改。
可以在不编写复杂的数据库查询和序列化器的情况下连接相关数据。

理解参数

Archie Core GraphQL API 的强大功能通过在执行查询时指定不同参数的能力得到进一步增强。这在上面的示例中已经演示，其中特定的 UUID 字符串作为参数传递给查询（...citiesById(id: "e14638cb...")）。

在 Data Builder 中创建数据表时，任何标记为唯一的字段都可以用作查询的参数。

例如，由于 Cities 表的 ID 字段设置为唯一（因为它是主键），我们可以查询特定的 City 记录：

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

变量

您可以使用 API Explorer 中的变量使查询可重用和动态。

要使用变量，您需要：

将查询中的静态值替换为 $variableName。
将 $variableName 声明为查询接受的变量之一。
在单独的变量字典中传递 variableName: value。

这是查询：

query MyQuery ($filter: StudentsFilter) {
  students(filter: $filter) {
    items {
      firstName
      email
    }
  }
}

这是变量：

{
  "filter": {
    "isActive": {
      "equals": true
    }
  }
}

这是结果：

{
  "data": {
    "students": {
      "items": [
        {
          "firstName": "James",
          "email": "james.smith@example.com"
        },
        {
          "firstName": "John",
          "email": "john.williams@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.brown@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.johnson@example.com"
        },
        {
          "firstName": "Elizabeth",
          "email": "elizabeth.davis@example.com"
        }
      ]
    }
  }
}

alt text

别名

别名用于返回具有与其字段名称不同的名称的对象。当在单个查询中获取具有不同参数的相同类型的对象时，这是必需的。

下面您可以看到第一个城市的别名为 “cityOne”：

query MyQuery {
  cityOne: citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
  }

  cityTwo: citiesById(id: "0174dc55-d494-4ebc-a0e9-13575461cad4") {
    id
    nameCity
  }
}

结果：

{
  "data": {
    "cityOne": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago"
    },
    "cityTwo": {
      "id": "0174dc55-d494-4ebc-a0e9-13575461cad4",
      "nameCity": "Miami"
    }
  }
}

片段

查询可能变得冗长而复杂。片段创建一组字段，可用于表示定义的集合。如果您想要来自两个不同作者的多个字段，可以使用片段，而不是重复字段两次。在此查询中，我们有一个名为 { ...studentFrag } 的片段：

query MyQuery {
  studentA: studentsById(id: "287cff0a-345b-4cca-9e9a-75a2161238fd") { ...studentFrag}

  studentB: studentsById(id: "97fb89ac-e0ad-44f5-b671-24a1b751287c") { ...studentFrag}
}

fragment studentFrag on Students {
      id
      firstName
      email
      isActive
      city {
        nameCity
        state
      }
    }

结果：

{
  "data": {
    "studentA": {
      "id": "287cff0a-345b-4cca-9e9a-75a2161238fd",
      "firstName": "James",
      "email": "james.smith@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Chicago",
        "state": "Illinois"
      }
    },
    "studentB": {
      "id": "97fb89ac-e0ad-44f5-b671-24a1b751287c",
      "firstName": "John",
      "email": "john.williams@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Seattle",
        "state": "Washington"
      }