Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

内置模块

模块是 APPSYNC_JS 运行时环境的一部分，模块提供实用程序以帮助编写 JavaScript 解析器和函数。

DynamoDB 模块函数

在与 DynamoDB 数据源交互时，DynamoDB 模块函数提供增强的体验。您可以使用这些函数向 DynamoDB 数据源发出请求，而无需添加类型映射。

模块是使用 @aws-appsync/utils/dynamodb 导入的：

// Modules are imported using @aws-appsync/utils/dynamodb
import * as ddb from '@aws-appsync/utils/dynamodb';

函数

操作

通过使用操作帮助程序，您可以在更新期间对部分数据执行特定的操作。要开始使用，请从 @aws-appsync/utils/dynamodb 中导入 operations：

// Modules are imported using operations
import {operations} from '@aws-appsync/utils/dynamodb';

输入

Amazon RDS 模块函数

在与使用 Amazon RDS 数据 API 配置的数据库进行交互时，Amazon RDS 模块函数可提供增强的体验。使用 @aws-appsync/utils/rds 导入模块：

import * as rds from '@aws-appsync/utils/rds';

也可以单独导入函数。例如，下面的导入使用 sql：

import { sql } from '@aws-appsync/utils/rds';

函数

您可以使用 Amazon AppSync RDS 模块的实用程序帮助程序与您的数据库进行交互。

Select

select 实用程序会创建一条 SELECT 语句来查询您的关系数据库。

基本用法

在其基本形式中，您可以指定要查询的表：

import { select, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {

    // Generates statement: 
    // "SELECT * FROM "persons"
    return createPgStatement(select({table: 'persons'}));
}

请注意，您也可以在表标识符中指定架构：

import { select, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {

    // Generates statement:
    // SELECT * FROM "private"."persons"
    return createPgStatement(select({table: 'private.persons'}));
}

指定列

您可以使用 columns 属性指定列。如果未将其设置为某个值，则它默认为 *：

export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name']
    }));
}

您也可以指定列的表：

export function request(ctx) {

    // Generates statement: 
    // SELECT "id", "persons"."name"
    // FROM "persons"
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'persons.name']
    }));
}

限制和偏移

您可以将 limit 和 offset 应用于查询：

export function request(ctx) {

    // Generates statement: 
    // SELECT "id", "name"
    // FROM "persons"
    // LIMIT :limit
    // OFFSET :offset
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        limit: 10,
        offset: 40
    }));
}

排序依据

您可以使用 orderBy 属性对结果进行排序。提供指定列和可选 dir 属性的对象数组：

export function request(ctx) {

    // Generates statement: 
    // SELECT "id", "name" FROM "persons"
    // ORDER BY "name", "id" DESC
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        orderBy: [{column: 'name'}, {column: 'id', dir: 'DESC'}]
    }));
}

筛选器

您可以使用特殊条件对象来构建筛选条件：

export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    // WHERE "name" = :NAME
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        where: {name: {eq: 'Stephane'}}
    }));
}

您也可以组合筛选条件：

export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    // WHERE "name" = :NAME and "id" > :ID
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        where: {name: {eq: 'Stephane'}, id: {gt: 10}}
    }));
}

您也可以创建 OR 语句：

export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    // WHERE "name" = :NAME OR "id" > :ID
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        where: { or: [
            { name: { eq: 'Stephane'} },
            { id: { gt: 10 } }
        ]}
    }));
}

您也可以使用 not 来否定条件：

export function request(ctx) {

    // Generates statement:
    // SELECT "id", "name"
    // FROM "persons"
    // WHERE NOT ("name" = :NAME AND "id" > :ID)
    return createPgStatement(select({
        table: 'persons',
        columns: ['id', 'name'],
        where: { not: [
            { name: { eq: 'Stephane'} },
            { id: { gt: 10 } }
        ]}
    }));
}

您也可以使用以下运算符来比较值：

Insert

insert 实用程序提供了一种通过 INSERT 操作在数据库中插入单行项目的简单方法。

单个项目插入

要插入项目，请指定表，然后传入您的值对象。对象键映射到您的表列。列名称会自动转义，并使用变量映射将值发送到数据库：

import { insert, createMySQLStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: values } = ctx.args;
    const insertStatement = insert({ table: 'persons', values });
    
    // Generates statement:
    // INSERT INTO `persons`(`name`)
    // VALUES(:NAME)
    return createMySQLStatement(insertStatement)
}

MySQL 用例

您可以组合 insert 后跟 select 来检索您插入的行：

import { insert, select, createMySQLStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: values } = ctx.args;
    const insertStatement = insert({  table: 'persons', values });
    const selectStatement = select({
        table: 'persons',
        columns: '*',
        where: { id: { eq: values.id } },
        limit: 1,
    });
    
    // Generates statement:
    // INSERT INTO `persons`(`name`)
    // VALUES(:NAME)
    // and
    // SELECT *
    // FROM `persons`
    // WHERE `id` = :ID
    return createMySQLStatement(insertStatement, selectStatement)
}

Postgres 用例

借助 Postgres，您可以使用 returning 从插入的行中获取数据。它接受 * 或列名称数组：

import { insert, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: values } = ctx.args;
    const insertStatement = insert({
        table: 'persons',
        values,
        returning: '*'
    });

    // Generates statement:
    // INSERT INTO "persons"("name")
    // VALUES(:NAME)
    // RETURNING *
    return createPgStatement(insertStatement)
}

更新

update 实用程序允许您更新现有行。您可以使用条件对象将更改应用于满足条件的所有行中的指定列。例如，假设我们有一个允许我们进行这种突变的架构。我们要将 Person 的 name 更新为 id 值 3，但仅限我们自 2000 年开始就已知道它们 (known_since)：

mutation Update {
    updatePerson(
        input: {id: 3, name: "Jon"},
        condition: {known_since: {ge: "2000"}}
    ) {
    id
    name
  }
}

更新解析器如下所示：

import { update, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: { id, ...values }, condition } = ctx.args;
    const where = {
        ...condition,
        id: { eq: id },
    };
    const updateStatement = update({
        table: 'persons',
        values,
        where,
        returning: ['id', 'name'],
    });

    // Generates statement:
    // UPDATE "persons"
    // SET "name" = :NAME, "birthday" = :BDAY, "country" = :COUNTRY
    // WHERE "id" = :ID
    // RETURNING "id", "name"
    return createPgStatement(updateStatement)
}

我们可以在条件中添加一项检查，以确保只更新主键 id 等于 3 的行。同样，对于 Postgres inserts，您可以使用 returning 返回修改后的数据。

删除

remove 实用程序允许您删除现有行。您可以在满足条件的所有行上使用条件对象。请注意，delete 是 JavaScript 中的保留关键字。应改用 remove：

import { remove, createPgStatement } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const { input: { id }, condition } = ctx.args;
    const where = { ...condition, id: { eq: id } };
    const deleteStatement = remove({
        table: 'persons',
        where,
        returning: ['id', 'name'],
    });

    // Generates statement:
    // DELETE "persons"
    // WHERE "id" = :ID
    // RETURNING "id", "name"
    return createPgStatement(updateStatement)
}

转换

在某些情况下，您可能希望在语句中使用更具体的正确对象类型。您可以使用提供的类型提示来指定参数的类型。Amazon AppSync 支持与数据 API 相同的类型提示。您可以使用 Amazon AppSync rds 模块中的 typeHint 函数来强制转换参数。

以下示例允许您将数组作为强制转换为 JSON 对象的值发送。我们使用 -> 运算符来检索 JSON 数组中 index 为 2 的元素：

import { sql, createPgStatement, toJsonObject, typeHint } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const arr = ctx.args.list_of_ids
    const statement = sql`select ${typeHint.JSON(arr)}->2 as value`
    return createPgStatement(statement)
}

export function response(ctx) {
    return toJsonObject(ctx.result)[0][0].value
}

在处理和比较 DATE、TIME 和 TIMESTAMP 时，强制转换也很有用：

import { select, createPgStatement, typeHint } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const when = ctx.args.when
    const statement = select({
        table: 'persons',
        where: { createdAt : { gt: typeHint.DATETIME(when) } }
    })
    return createPgStatement(statement)
}

下面是另一个示例，显示如何发送当前日期和时间：

import { sql, createPgStatement, typeHint } from '@aws-appsync/utils/rds';

export function request(ctx) {
    const now = util.time.nowFormatted('YYYY-MM-dd HH:mm:ss')
    return createPgStatement(sql`select ${typeHint.TIMESTAMP(now)}`)
}

可用的类型提示