Syntaxe Propriétés Valeurs renvoyées Exemples

AWS::Serverless: :GraphQLAPI

Utilisez le type de AWS::Serverless::GraphQLApi ressource AWS Serverless Application Model (AWS SAM) pour créer et configurer une AWS AppSync GraphQL API pour votre application sans serveur.

Pour en savoir plus AWS AppSync, voir Qu'est-ce que c'est AWS AppSync ? dans le Guide AWS AppSync du développeur.

Syntaxe

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

Propriétés

ApiKeys

Créez une clé unique qui peut être utilisée pour effectuer des opérations GraphQL nécessitant une clé d'API.

Type : ApiKeys

Obligatoire : non

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

Auth

Configurez l'authentification pour votre API GraphQL.

Type : Authentification

Obligatoire : oui

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

Cache

Entrée d'une opération CreateApiCache.

Type AWS::AppSync : : ApiCache

Obligatoire : non

CloudFormation compatibilité : Cette propriété est transmise directement à la ApiCache ressource AWS::AppSync: :.

DataSources

Créez des sources de données auxquelles les fonctions AWS AppSync peuvent se connecter. AWS SAM prend en charge Amazon DynamoDB et les sources de données AWS Lambda .

Type : DataSource

Obligatoire : oui

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

DomainName

Nom de domaine personnalisé pour votre API GraphQL.

Type AWS::AppSync : : DomainName

Obligatoire : non

CloudFormation compatibilité : Cette propriété est transmise directement à la DomainName ressource AWS::AppSync: :. AWS SAM génère automatiquement la DomainNameApiAssociation ressource AWS::AppSync: :.

Functions

Configurez les fonctions des API GraphQL pour effectuer certaines opérations.

Type : Fonction

Obligatoire : oui

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

Logging

Configure la CloudWatch journalisation Amazon pour votre GraphQL API.

Si vous ne spécifiez pas cette propriété, AWS SAM générera CloudWatchLogsRoleArn et définira les valeurs suivantes :

ExcludeVerboseContent: true
FieldLogLevel: ALL

Pour désactiver la journalisation, spécifiez les informations suivantes :


Logging: false

Type : LogConfig

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la LogConfig propriété d'une AWS::AppSync::GraphQLApi ressource.

LogicalId

Le nom unique de votre API GraphQL.

Type : chaîne

Obligatoire : oui

CloudFormation compatibilité : cette propriété est transmise directement à la Name propriété d'une AWS::AppSync::GraphQLApi ressource.

Name

Nom de votre API GraphQL. Spécifiez cette propriété pour remplacer la valeur LogicalId.

Type : chaîne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la Name propriété d'une AWS::AppSync::GraphQLApi ressource.

Resolvers

Configurez des résolveurs pour les champs de votre API GraphQL. AWS SAM prend en charge les résolveurs de pipelines JavaScript.

Type : Résolveur

Obligatoire : oui

CloudFormation compatibilité : cette propriété est unique AWS SAM et n'a pas d' CloudFormation équivalent.

SchemaInline

Représentation texte d'un schéma GraphQL au format SDL.

Type : chaîne

Obligatoire : selon les conditions. Vous devez spécifier SchemaInline ou SchemaUri.

CloudFormation compatibilité : cette propriété est transmise directement à la Definition propriété d'une AWS::AppSync::GraphQLSchema ressource.

SchemaUri

L'URI du compartiment Amazon Simple Storage Service (Amazon S3) du schéma ou le chemin d'accès à un dossier local.

Si vous spécifiez un chemin d'accès à un dossier local, le fichier CloudFormation doit d'abord être chargé sur Amazon S3 avant le déploiement. Vous pouvez utiliser la CLI AWS SAM pour faciliter ce processus. Pour plus d’informations, consultez Comment ? AWS SAM télécharge les fichiers locaux lors du déploiement.

Type : chaîne

Obligatoire : selon les conditions. Vous devez spécifier SchemaInline ou SchemaUri.

CloudFormation compatibilité : cette propriété est transmise directement à la DefinitionS3Location propriété d'une AWS::AppSync::GraphQLSchema ressource.

Tags

Balises (paires clé-valeur) pour cette API GraphQL. Utilisez les balises pour identifier et classer les ressources.

Type : liste des éléments Tag

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la Tag propriété d'une AWS::AppSync::GraphQLApi ressource.

XrayEnabled

Indiquez si vous souhaitez utiliser le AWS X-Ray suivi pour cette ressource.

Type : valeur booléenne

Obligatoire : non

CloudFormation compatibilité : cette propriété est transmise directement à la XrayEnabled propriété d'une AWS::AppSync::GraphQLApi ressource.

Valeurs renvoyées

Pour obtenir la liste des valeurs renvoyées, reportez-vous AWS::Serverless::GraphQLApiau Guide de l'CloudFormation utilisateur.

Exemples

API GraphQL avec la source de données DynamoDB

Dans cet exemple, nous créons une API GraphQL qui utilise une table DynamoDB comme source de données.

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),
  };
}

prétraitement PostItem.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;
}

Voici notre code de résolution :

getPost.js


export function request(ctx) {
  return {};
}

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

GraphQL API avec une fonction d'événement Lambda comme source de données

Dans cet exemple, nous créons une GraphQL API qui utilise une fonction d'événement Lambda comme source de données.

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
}

Voici nos fonctions :

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;
}

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

FunctionScalingConfig

ApiKeys