This plugin wraps AppSync and serverless-appsync-plugin into a new format which requires less configurations.
npm install @appsync/serverless-plugin@AWSLambda() and it will be deployed.Install the plugin using NPM:
``sh`
npm install --save-dev @appsync/serverless-plugin
Or Yarn:
`sh`
yarn add --dev @appsync/serverless-plugin
Add it into your serverless.yml settings:
`yml`
plugins:
- '@appsync/serverless-plugin'serverless-appsync-plugin
_Note, if you were using , remove it, since this plugins wraps it_.
Set Settings:
`yml`
custom:
appSync:
schema: schema.graphql # If you're not using Schema stitching, you can specify a single graphql file here.
prefix: 'some_prefix' # If you want to prefix aws lambda names, here you can add a prefix.
schemaDir: Controllers/ # Directory to find out the .graphql schemas (Schema stitching), this overrides "schema" field.
authenticationType: API_KEY #See serverless-appsync-plugin documentation.
name: ${self:service.name}_${self:provider.stage} #See serverless-appsync-plugin documentation.
serviceRole: 'AppSyncServiceRole' #See 'dataSources.config.serviceRoleArn' serverless-appsync-plugin documentation.
Create your first function:
Create any .graphql file under schemaDir directory like this:
`graphql
type Author {
name: String
}
type Todo {
id: String!
text: String!
title: String!
author: Author!
@AWSLambda(handler: "Controllers/Todo/Author/index.default")
}
type Query {
GetTodo(id: String!): Todo!
@AWSLambda(handler: "Controllers/Todo/GetTodo.default")
SearchTodo(search: String!): [Todo!]
@AWSLambda(handler: "Controllers/Todo/SearchTodo.default")
}
schema {
query: Query
}
`
Replace schema and types accordingly, "handler" should point to the function you want to bind
to this lambda.
Event Shape:
##### Request Event:
When your lambdas are called, the following request is sent on the lambda's first parameter:
`jsonGetTodo
{
// Arguments Received from the call (see as example).author
"args": {
"id": "6w4d3xpnevfrdemm7qmpo375fq"
},
// If this is a query as was within a field, you'll receive his parent value here.
// (see field as example, on parent you'll receive the Todo)`
"parent": null,
// Headers from the request, in a key-value object.
"headers": {
"authorization": "Bearer eyJh.......90",
"sec-fetch-dest": "empty",
"cloudfront-is-desktop-viewer": "true",
"sec-fetch-site": "same-origin",
"x-forwarded-port": "443"
}
}
##### Successful Response:
If everything worked well, you can return data to the client by returning:
`jsondata
{
// Remember, should match the response type of your graphql field, thisGetTodo
// is the example of `
"data": {
"id": "6w4d3xpnevfrdemm7qmpo375fq",
"text": "This is your note body, you can put things here",
"title": "An ordinary note"
}
}
##### Failed Response:
If an error ocurred, we'll format it accordingly if error property is returned:`json`
{
"error": {
"name": "NotFound",
"message": "Todo not found",
"other_field": "any other field that you like to return to the client"
}
}name
For proper formatting, please return and message on those errors.
: Will Validate your schema/schemas, throwing an error if an issue is found.
- serverless generate-types: Will generate an example of the output serverless type.
$3
- custom.appSync.schema:
If custom.appSync.schemaDir is found, it will override custom.appSync.schema.$3
Please refer to Serverless Appsync Plugin for documentation on original fields.
Extra fields includes:
`yml
appSync:
schema: schema.graphql # Reference a single graphql schema field to use as definition.
schemaDir: Controllers/ # Directory to find out the .graphql schemas using schema stitching. This overrides "schema" field.
serviceRole: 'AppSyncServiceRole' #See 'dataSources.config.serviceRoleArn' serverless-appsync-plugin documentation.
` -
schemaDir: Setting this field the plugin will set schema stitching by picking any .graphql file under this directory.
- request / response: Points to a Mapping Template File, see Configuring the plugin for more info.
- serviceRole: Where AppSyncDynamoDBServiceRole is an IAM role defined in Resources, see "Example ServiceRole"
$3
`yml
resources:
Resources:
AppSyncServiceRole:
Type: "AWS::IAM::Role"
Properties:
RoleName: ${self:custom.appSync.name}-Lambda-AppSyncServiceRole
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: "Allow"
Principal:
Service:
- "appsync.amazonaws.com"
Action:
- "sts:AssumeRole" Policies:
- PolicyName: ${self:custom.appSync.name}-Lambda-AppSyncServiceRole-Policy
PolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: "Allow"
Action:
- "lambda:invokeFunction"
Resource:
- "*"
`The
@AWSLambda Directive:$3
@AWSLambda flags the following field to be resolved with a function:
`gql
It can be used on a root type:
type Query {
GetTodo(id: String!): Todo!
@AWSLambda(handler: "Controllers/Todo/GetTodo.default")
}Or within another type:
type Todo {
id: String!
text: String!
title: String!
author: Author!
@AWSLambda(handler: "Controllers/Todo/Author/index.default")
}
`Parameters:
- handler`: Handler receives a string with the path of where the function is