AWS::Serverless::GraphQLApi - AWS Serverless Application Model

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

AWS::Serverless::GraphQLApi

使用 AWS Serverless Application Model (AWS SAM) AWS::Serverless::GraphQLApi 资源类型为您的无服务器应用程序创建和配置 AWS AppSync GraphQL API。

若要了解 AWS AppSync 的更多信息,请参阅《AWS AppSync 开发人员指南》中的什么是 AWS AppSync?

语法

YAML

LogicalId: Type: AWS::Serverless::GraphQLApi Properties: ApiKeys: ApiKeys Auth: Auth Cache: AWS::AppSync::ApiCache DataSources: DataSource DomainName: AWS::AppSync::DomainName Functions: Function Logging: LogConfig Name: String Resolvers: Resolver SchemaInline: String SchemaUri: String Tags: - Tag XrayEnabled: Boolean

属性

ApiKeys

创建可用于执行需要 API 密钥的 GraphQL 操作的唯一密钥。

类型Api 密钥

必需:否

AWS CloudFormation 兼容性:此属性为 AWS SAM 独有,没有 AWS CloudFormation 等效属性。

Auth

为您的 GraphQL API 配置身份验证。

类型身份验证

必需:是

AWS CloudFormation 兼容性:此属性为 AWS SAM 独有,没有 AWS CloudFormation 等效属性。

Cache

CreateApiCache 操作的输入。

类型AWS::AppSync::ApiCache

必需:否

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::ApiCache 资源。

DataSources

为 AWS AppSync 中的函数创建要连接的数据来源。AWS SAM 支持 Amazon DynamoDB 和 AWS Lambda 数据来源。

类型DataSource

必需:是

AWS CloudFormation 兼容性:此属性为 AWS SAM 独有,没有 AWS CloudFormation 等效属性。

DomainName

GraphQL API 的自定义域名。

类型AWS::AppSync::DomainName

必需:否

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::DomainName 资源。AWS SAM 自动生成 AWS::AppSync::DomainNameApiAssociation 资源。

Functions

在 GraphQL API 中配置函数以执行某些操作。

类型函数

必需:是

AWS CloudFormation 兼容性:此属性为 AWS SAM 独有,没有 AWS CloudFormation 等效属性。

Logging

为您的 GraphQL API 配置 Amazon CloudWatch 日志记录。

如果不指定此属性,AWS SAM 将生成 CloudWatchLogsRoleArn 并设置以下值:

  • ExcludeVerboseContent: true

  • FieldLogLevel: ALL

要选择退出日志记录,请指定以下内容:

Logging: false

类型LogConfig

必需:否

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::GraphQLApi 资源的 LogConfig 属性。

LogicalId

您的 GraphQL API 的唯一名称。

类型:字符串

必需:是

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::GraphQLApi 资源的 Name 属性。

Name

GraphQL API 的名称。指定此属性以覆盖 LogicalId 值。

类型:字符串

必需:否

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::GraphQLApi 资源的 Name 属性。

Resolvers

为 GraphQL API 的字段配置解析程序。AWS SAM 支持 JavaScript 管道解析程序

类型解析程序

必需:是

AWS CloudFormation 兼容性:此属性为 AWS SAM 独有,没有 AWS CloudFormation 等效属性。

SchemaInline

GraphQL 架构的 SDL 格式的文本表示。

类型:字符串

必填:条件性。您必须指定 SchemaInlineSchemaUri

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::GraphQLSchema 资源的 Definition 属性。

SchemaUri

架构的 Amazon Simple Storage Service (Amazon S3) 存储桶 URI 或本地文件夹的路径。

如果您指定本地文件夹的路径,则 AWS CloudFormation 会要求在部署前先将该文件上传到 Amazon S3。您可以使用 AWS SAM CLI 来简化此过程。有关更多信息,请参阅 如何在 AWS SAM 部署时上传本地文件

类型:字符串

必填:条件性。您必须指定 SchemaInlineSchemaUri

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::GraphQLSchema 资源的 DefinitionS3Location 属性。

Tags

此 GraphQL API 的标签(键值对)。使用标签标识和分类资源。

类型:标签列表

必需:否

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::GraphQLApi 资源的 Tag 属性。

XrayEnabled

指明是否对此资源使用 AWS X-Ray 跟踪

类型:布尔值

必需:否

AWS CloudFormation 兼容性:此属性直接传递给 AWS::AppSync::GraphQLApi 资源的 XrayEnabled 属性。

示例

以 DynamoDB 为数据来源的 GraphQL API

在此示例中,我们创建了一个使用 DynamoDB 表作为数据来源的 GraphQL API。

schema.graphql

schema { query: Query mutation: Mutation } type Query { getPost(id: String!): Post } type Mutation { addPost(author: String!, title: String!, content: String!): Post! } type Post { id: String! author: String title: String content: String ups: Int! downs: Int! version: Int! }

template.yaml

AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 ... Resources: DynamoDBPostsTable: Type: AWS::Serverless::SimpleTable MyGraphQLAPI: Type: AWS::Serverless::GraphQLApi Properties: SchemaUri: ./sam_graphql_api/schema.graphql Auth: Type: AWS_IAM DataSources: DynamoDb: PostsDataSource: TableName: !Ref DynamoDBPostsTable TableArn: !GetAtt DynamoDBPostsTable.Arn Functions: preprocessPostItem: Runtime: Name: APPSYNC_JS Version: 1.0.0 DataSource: NONE CodeUri: ./sam_graphql_api/preprocessPostItem.js createPostItem: Runtime: Name: APPSYNC_JS Version: "1.0.0" DataSource: PostsDataSource CodeUri: ./sam_graphql_api/createPostItem.js getPostFromTable: Runtime: Name: APPSYNC_JS Version: "1.0.0" DataSource: PostsDataSource CodeUri: ./sam_graphql_api/getPostFromTable.js Resolvers: Mutation: addPost: Runtime: Name: APPSYNC_JS Version: "1.0.0" Pipeline: - preprocessPostItem - createPostItem Query: getPost: CodeUri: ./sam_graphql_api/getPost.js Runtime: Name: APPSYNC_JS Version: "1.0.0" Pipeline: - getPostFromTable

createPostItem.js

import { util } from "@aws-appsync/utils"; export function request(ctx) { const { key, values } = ctx.prev.result; return { operation: "PutItem", key: util.dynamodb.toMapValues(key), attributeValues: util.dynamodb.toMapValues(values), }; } export function response(ctx) { return ctx.result; }

getPostFromTable.js

import { util } from "@aws-appsync/utils"; export function request(ctx) { return dynamoDBGetItemRequest({ id: ctx.args.id }); } export function response(ctx) { return ctx.result; } /** * A helper function to get a DynamoDB item */ function dynamoDBGetItemRequest(key) { return { operation: "GetItem", key: util.dynamodb.toMapValues(key), }; }

preprocessPostItem.js

import { util } from "@aws-appsync/utils"; export function request(ctx) { const id = util.autoId(); const { ...values } = ctx.args; values.ups = 1; values.downs = 0; values.version = 1; return { payload: { key: { id }, values: values } }; } export function response(ctx) { return ctx.result; }

解析程序代码如下:

getPost.js

export function request(ctx) { return {}; } export function response(ctx) { return ctx.prev.result; }

以 Lambda 函数为数据来源的 GraphQL API

在此示例中,我们创建了一个使用 Lambda 函数作为数据来源的 GraphQL API。

template.yaml

AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 ... Resources: MyLambdaFunction: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: nodejs20.x CodeUri: ./lambda MyGraphQLAPI: Type: AWS::Serverless::GraphQLApi Properties: Name: MyApi SchemaUri: ./gql/schema.gql Auth: Type: API_KEY ApiKeys: MyApiKey: Description: my api key DataSources: Lambda: MyLambdaDataSource: FunctionArn: !GetAtt MyLambdaFunction.Arn Functions: lambdaInvoker: Runtime: Name: APPSYNC_JS Version: 1.0.0 DataSource: MyLambdaDataSource CodeUri: ./gql/invoker.js Resolvers: Mutation: addPost: Runtime: Name: APPSYNC_JS Version: 1.0.0 Pipeline: - lambdaInvoker Query: getPost: Runtime: Name: APPSYNC_JS Version: 1.0.0 Pipeline: - lambdaInvoker Outputs: MyGraphQLAPI: Description: AppSync API Value: !GetAtt MyGraphQLAPI.GraphQLUrl MyGraphQLAPIMyApiKey: Description: API Key for authentication Value: !GetAtt MyGraphQLAPIMyApiKey.ApiKey

schema.graphql

schema { query: Query mutation: Mutation } type Query { getPost(id: ID!): Post } type Mutation { addPost(id: ID!, author: String!, title: String, content: String): Post! } type Post { id: ID! author: String! title: String content: String ups: Int downs: Int }

函数如下:

lambda/index.js

exports.handler = async (event) => { console.log("Received event {}", JSON.stringify(event, 3)); const posts = { 1: { id: "1", title: "First book", author: "Author1", content: "Book 1 has this content", ups: "100", downs: "10", }, }; console.log("Got an Invoke Request."); let result; switch (event.field) { case "getPost": return posts[event.arguments.id]; case "addPost": // return the arguments back return event.arguments; default: throw new Error("Unknown field, unable to resolve " + event.field); } };

invoker.js

import { util } from "@aws-appsync/utils"; export function request(ctx) { const { source, args } = ctx; return { operation: "Invoke", payload: { field: ctx.info.fieldName, arguments: args, source }, }; } export function response(ctx) { return ctx.result; }