diff options
Diffstat (limited to 'python-aws-cdk-aws-appsync-alpha.spec')
| -rw-r--r-- | python-aws-cdk-aws-appsync-alpha.spec | 1343 |
1 files changed, 1343 insertions, 0 deletions
diff --git a/python-aws-cdk-aws-appsync-alpha.spec b/python-aws-cdk-aws-appsync-alpha.spec new file mode 100644 index 0000000..ab150d2 --- /dev/null +++ b/python-aws-cdk-aws-appsync-alpha.spec @@ -0,0 +1,1343 @@ +%global _empty_manifest_terminate_build 0 +Name: python-aws-cdk.aws-appsync-alpha +Version: 2.59.0a0 +Release: 1 +Summary: The CDK Construct Library for AWS::AppSync +License: Apache-2.0 +URL: https://github.com/aws/aws-cdk +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/95/fb/68594bd88a22aed241f6c98babfb352388263207d91aaf8bc181055623b6/aws-cdk.aws-appsync-alpha-2.59.0a0.tar.gz +BuildArch: noarch + +Requires: python3-aws-cdk-lib +Requires: python3-constructs +Requires: python3-jsii +Requires: python3-publication +Requires: python3-typeguard + +%description +<!--END STABILITY BANNER--> +The `@aws-cdk/aws-appsync` package contains constructs for building flexible +APIs that use GraphQL. +```python +import aws_cdk.aws_appsync_alpha as appsync +``` +## Example +### DynamoDB +Example of a GraphQL API with `AWS_IAM` [authorization](#authorization) resolving into a DynamoDb +backend data source. +GraphQL schema file `schema.graphql`: +```gql +type demo { + id: String! + version: String! +} +type Query { + getDemos: [ demo! ] +} +input DemoInput { + version: String! +} +type Mutation { + addDemo(input: DemoInput!): demo +} +``` +CDK stack file `app-stack.ts`: +```python +api = appsync.GraphqlApi(self, "Api", + name="demo", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphql")), + authorization_config=appsync.AuthorizationConfig( + default_authorization=appsync.AuthorizationMode( + authorization_type=appsync.AuthorizationType.IAM + ) + ), + xray_enabled=True +) +demo_table = dynamodb.Table(self, "DemoTable", + partition_key=dynamodb.Attribute( + name="id", + type=dynamodb.AttributeType.STRING + ) +) +demo_dS = api.add_dynamo_db_data_source("demoDataSource", demo_table) +# Resolver for the Query "getDemos" that scans the DynamoDb table and returns the entire list. +# Resolver Mapping Template Reference: +# https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html +demo_dS.create_resolver("QueryGetDemosResolver", + type_name="Query", + field_name="getDemos", + request_mapping_template=appsync.MappingTemplate.dynamo_db_scan_table(), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_list() +) +# Resolver for the Mutation "addDemo" that puts the item into the DynamoDb table. +demo_dS.create_resolver("MutationAddDemoResolver", + type_name="Mutation", + field_name="addDemo", + request_mapping_template=appsync.MappingTemplate.dynamo_db_put_item( + appsync.PrimaryKey.partition("id").auto(), + appsync.Values.projecting("input")), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_item() +) +# To enable DynamoDB read consistency with the `MappingTemplate`: +demo_dS.create_resolver("QueryGetDemosConsistentResolver", + type_name="Query", + field_name="getDemosConsistent", + request_mapping_template=appsync.MappingTemplate.dynamo_db_scan_table(True), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_list() +) +``` +### Aurora Serverless +AppSync provides a data source for executing SQL commands against Amazon Aurora +Serverless clusters. You can use AppSync resolvers to execute SQL statements +against the Data API with GraphQL queries, mutations, and subscriptions. +```python +# Build a data source for AppSync to access the database. +# api: appsync.GraphqlApi +# Create username and password secret for DB Cluster +secret = rds.DatabaseSecret(self, "AuroraSecret", + username="clusteradmin" +) +# The VPC to place the cluster in +vpc = ec2.Vpc(self, "AuroraVpc") +# Create the serverless cluster, provide all values needed to customise the database. +cluster = rds.ServerlessCluster(self, "AuroraCluster", + engine=rds.DatabaseClusterEngine.AURORA_MYSQL, + vpc=vpc, + credentials={"username": "clusteradmin"}, + cluster_identifier="db-endpoint-test", + default_database_name="demos" +) +rds_dS = api.add_rds_data_source("rds", cluster, secret, "demos") +# Set up a resolver for an RDS query. +rds_dS.create_resolver("QueryGetDemosRdsResolver", + type_name="Query", + field_name="getDemosRds", + request_mapping_template=appsync.MappingTemplate.from_string(""" + { + "version": "2018-05-29", + "statements": [ + "SELECT * FROM demos" + ] + } + """), + response_mapping_template=appsync.MappingTemplate.from_string(""" + $utils.toJson($utils.rds.toJsonObject($ctx.result)[0]) + """) +) +# Set up a resolver for an RDS mutation. +rds_dS.create_resolver("MutationAddDemoRdsResolver", + type_name="Mutation", + field_name="addDemoRds", + request_mapping_template=appsync.MappingTemplate.from_string(""" + { + "version": "2018-05-29", + "statements": [ + "INSERT INTO demos VALUES (:id, :version)", + "SELECT * WHERE id = :id" + ], + "variableMap": { + ":id": $util.toJson($util.autoId()), + ":version": $util.toJson($ctx.args.version) + } + } + """), + response_mapping_template=appsync.MappingTemplate.from_string(""" + $utils.toJson($utils.rds.toJsonObject($ctx.result)[1][0]) + """) +) +``` +### HTTP Endpoints +GraphQL schema file `schema.graphql`: +```gql +type job { + id: String! + version: String! +} +input DemoInput { + version: String! +} +type Mutation { + callStepFunction(input: DemoInput!): job +} +``` +GraphQL request mapping template `request.vtl`: +```json +{ + "version": "2018-05-29", + "method": "POST", + "resourcePath": "/", + "params": { + "headers": { + "content-type": "application/x-amz-json-1.0", + "x-amz-target":"AWSStepFunctions.StartExecution" + }, + "body": { + "stateMachineArn": "<your step functions arn>", + "input": "{ \"id\": \"$context.arguments.id\" }" + } + } +} +``` +GraphQL response mapping template `response.vtl`: +```json +{ + "id": "${context.result.id}" +} +``` +CDK stack file `app-stack.ts`: +```python +api = appsync.GraphqlApi(self, "api", + name="api", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphql")) +) +http_ds = api.add_http_data_source("ds", "https://states.amazonaws.com", + name="httpDsWithStepF", + description="from appsync to StepFunctions Workflow", + authorization_config=appsync.AwsIamConfig( + signing_region="us-east-1", + signing_service_name="states" + ) +) +http_ds.create_resolver("MutationCallStepFunctionResolver", + type_name="Mutation", + field_name="callStepFunction", + request_mapping_template=appsync.MappingTemplate.from_file("request.vtl"), + response_mapping_template=appsync.MappingTemplate.from_file("response.vtl") +) +``` +### Amazon OpenSearch Service +AppSync has builtin support for Amazon OpenSearch Service (successor to Amazon +Elasticsearch Service) from domains that are provisioned through your AWS account. You can +use AppSync resolvers to perform GraphQL operations such as queries, mutations, and +subscriptions. +```python +import aws_cdk.aws_opensearchservice as opensearch +# api: appsync.GraphqlApi +user = iam.User(self, "User") +domain = opensearch.Domain(self, "Domain", + version=opensearch.EngineVersion.OPENSEARCH_1_3, + removal_policy=RemovalPolicy.DESTROY, + fine_grained_access_control=opensearch.AdvancedSecurityOptions(master_user_arn=user.user_arn), + encryption_at_rest=opensearch.EncryptionAtRestOptions(enabled=True), + node_to_node_encryption=True, + enforce_https=True +) +ds = api.add_open_search_data_source("ds", domain) +ds.create_resolver("QueryGetTestsResolver", + type_name="Query", + field_name="getTests", + request_mapping_template=appsync.MappingTemplate.from_string(JSON.stringify({ + "version": "2017-02-28", + "operation": "GET", + "path": "/id/post/_search", + "params": { + "headers": {}, + "query_string": {}, + "body": {"from": 0, "size": 50} + } + })), + response_mapping_template=appsync.MappingTemplate.from_string("""[ + #foreach($entry in $context.result.hits.hits) + #if( $velocityCount > 1 ) , #end + $utils.toJson($entry.get("_source")) + #end + ]""") +) +``` +## Custom Domain Names +For many use cases you may want to associate a custom domain name with your +GraphQL API. This can be done during the API creation. +```python +import aws_cdk.aws_certificatemanager as acm +import aws_cdk.aws_route53 as route53 +# hosted zone and route53 features +# hosted_zone_id: str +zone_name = "example.com" +my_domain_name = "api.example.com" +certificate = acm.Certificate(self, "cert", domain_name=my_domain_name) +schema = appsync.SchemaFile(file_path="mySchemaFile") +api = appsync.GraphqlApi(self, "api", + name="myApi", + schema=schema, + domain_name=appsync.DomainOptions( + certificate=certificate, + domain_name=my_domain_name + ) +) +# hosted zone for adding appsync domain +zone = route53.HostedZone.from_hosted_zone_attributes(self, "HostedZone", + hosted_zone_id=hosted_zone_id, + zone_name=zone_name +) +# create a cname to the appsync domain. will map to something like xxxx.cloudfront.net +route53.CnameRecord(self, "CnameApiRecord", + record_name="api", + zone=zone, + domain_name=api.app_sync_domain_name +) +``` +## Log Group +AppSync automatically create a log group with the name `/aws/appsync/apis/<graphql_api_id>` upon deployment with +log data set to never expire. If you want to set a different expiration period, use the `logConfig.retention` property. +To obtain the GraphQL API's log group as a `logs.ILogGroup` use the `logGroup` property of the +`GraphqlApi` construct. +```python +import aws_cdk.aws_logs as logs +log_config = appsync.LogConfig( + retention=logs.RetentionDays.ONE_WEEK +) +appsync.GraphqlApi(self, "api", + authorization_config=appsync.AuthorizationConfig(), + name="myApi", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "myApi.graphql")), + log_config=log_config +) +``` +## Schema +You can define a schema using from a local file using `SchemaFile.fromAsset` +```python +api = appsync.GraphqlApi(self, "api", + name="myApi", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphl")) +) +``` +### ISchema +Alternative schema sources can be defined by implementing the `ISchema` +interface. An example of this is the `CodeFirstSchema` class provided in +[awscdk-appsync-utils](https://github.com/cdklabs/awscdk-appsync-utils) +## Imports +Any GraphQL Api that has been created outside the stack can be imported from +another stack into your CDK app. Utilizing the `fromXxx` function, you have +the ability to add data sources and resolvers through a `IGraphqlApi` interface. +```python +# api: appsync.GraphqlApi +# table: dynamodb.Table +imported_api = appsync.GraphqlApi.from_graphql_api_attributes(self, "IApi", + graphql_api_id=api.api_id, + graphql_api_arn=api.arn +) +imported_api.add_dynamo_db_data_source("TableDataSource", table) +``` +If you don't specify `graphqlArn` in `fromXxxAttributes`, CDK will autogenerate +the expected `arn` for the imported api, given the `apiId`. For creating data +sources and resolvers, an `apiId` is sufficient. +## Authorization +There are multiple authorization types available for GraphQL API to cater to different +access use cases. They are: +* API Keys (`AuthorizationType.API_KEY`) +* Amazon Cognito User Pools (`AuthorizationType.USER_POOL`) +* OpenID Connect (`AuthorizationType.OPENID_CONNECT`) +* AWS Identity and Access Management (`AuthorizationType.AWS_IAM`) +* AWS Lambda (`AuthorizationType.AWS_LAMBDA`) +These types can be used simultaneously in a single API, allowing different types of clients to +access data. When you specify an authorization type, you can also specify the corresponding +authorization mode to finish defining your authorization. For example, this is a GraphQL API +with AWS Lambda Authorization. +```python +import aws_cdk.aws_lambda as lambda_ +# auth_function: lambda.Function +appsync.GraphqlApi(self, "api", + name="api", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "appsync.test.graphql")), + authorization_config=appsync.AuthorizationConfig( + default_authorization=appsync.AuthorizationMode( + authorization_type=appsync.AuthorizationType.LAMBDA, + lambda_authorizer_config=appsync.LambdaAuthorizerConfig( + handler=auth_function + ) + ) + ) +) +``` +## Permissions +When using `AWS_IAM` as the authorization type for GraphQL API, an IAM Role +with correct permissions must be used for access to API. +When configuring permissions, you can specify specific resources to only be +accessible by `IAM` authorization. For example, if you want to only allow mutability +for `IAM` authorized access you would configure the following. +In `schema.graphql`: +```gql +type Mutation { + updateExample(...): ... + @aws_iam +} +``` +In `IAM`: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "appsync:GraphQL" + ], + "Resource": [ + "arn:aws:appsync:REGION:ACCOUNT_ID:apis/GRAPHQL_ID/types/Mutation/fields/updateExample" + ] + } + ] +} +``` +See [documentation](https://docs.aws.amazon.com/appsync/latest/devguide/security.html#aws-iam-authorization) for more details. +To make this easier, CDK provides `grant` API. +Use the `grant` function for more granular authorization. +```python +# api: appsync.GraphqlApi +role = iam.Role(self, "Role", + assumed_by=iam.ServicePrincipal("lambda.amazonaws.com") +) +api.grant(role, appsync.IamResource.custom("types/Mutation/fields/updateExample"), "appsync:GraphQL") +``` +### IamResource +In order to use the `grant` functions, you need to use the class `IamResource`. +* `IamResource.custom(...arns)` permits custom ARNs and requires an argument. +* `IamResouce.ofType(type, ...fields)` permits ARNs for types and their fields. +* `IamResource.all()` permits ALL resources. +### Generic Permissions +Alternatively, you can use more generic `grant` functions to accomplish the same usage. +These include: +* grantMutation (use to grant access to Mutation fields) +* grantQuery (use to grant access to Query fields) +* grantSubscription (use to grant access to Subscription fields) +```python +# api: appsync.GraphqlApi +# role: iam.Role +# For generic types +api.grant_mutation(role, "updateExample") +# For custom types and granular design +api.grant(role, appsync.IamResource.of_type("Mutation", "updateExample"), "appsync:GraphQL") +``` +## Pipeline Resolvers and AppSync Functions +AppSync Functions are local functions that perform certain operations onto a +backend data source. Developers can compose operations (Functions) and execute +them in sequence with Pipeline Resolvers. +```python +# api: appsync.GraphqlApi +appsync_function = appsync.AppsyncFunction(self, "function", + name="appsync_function", + api=api, + data_source=api.add_none_data_source("none"), + request_mapping_template=appsync.MappingTemplate.from_file("request.vtl"), + response_mapping_template=appsync.MappingTemplate.from_file("response.vtl") +) +``` +AppSync Functions are used in tandem with pipeline resolvers to compose multiple +operations. +```python +# api: appsync.GraphqlApi +# appsync_function: appsync.AppsyncFunction +pipeline_resolver = appsync.Resolver(self, "pipeline", + api=api, + data_source=api.add_none_data_source("none"), + type_name="typeName", + field_name="fieldName", + request_mapping_template=appsync.MappingTemplate.from_file("beforeRequest.vtl"), + pipeline_config=[appsync_function], + response_mapping_template=appsync.MappingTemplate.from_file("afterResponse.vtl") +) +``` +Learn more about Pipeline Resolvers and AppSync Functions [here](https://docs.aws.amazon.com/appsync/latest/devguide/pipeline-resolvers.html). + +%package -n python3-aws-cdk.aws-appsync-alpha +Summary: The CDK Construct Library for AWS::AppSync +Provides: python-aws-cdk.aws-appsync-alpha +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-aws-cdk.aws-appsync-alpha +<!--END STABILITY BANNER--> +The `@aws-cdk/aws-appsync` package contains constructs for building flexible +APIs that use GraphQL. +```python +import aws_cdk.aws_appsync_alpha as appsync +``` +## Example +### DynamoDB +Example of a GraphQL API with `AWS_IAM` [authorization](#authorization) resolving into a DynamoDb +backend data source. +GraphQL schema file `schema.graphql`: +```gql +type demo { + id: String! + version: String! +} +type Query { + getDemos: [ demo! ] +} +input DemoInput { + version: String! +} +type Mutation { + addDemo(input: DemoInput!): demo +} +``` +CDK stack file `app-stack.ts`: +```python +api = appsync.GraphqlApi(self, "Api", + name="demo", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphql")), + authorization_config=appsync.AuthorizationConfig( + default_authorization=appsync.AuthorizationMode( + authorization_type=appsync.AuthorizationType.IAM + ) + ), + xray_enabled=True +) +demo_table = dynamodb.Table(self, "DemoTable", + partition_key=dynamodb.Attribute( + name="id", + type=dynamodb.AttributeType.STRING + ) +) +demo_dS = api.add_dynamo_db_data_source("demoDataSource", demo_table) +# Resolver for the Query "getDemos" that scans the DynamoDb table and returns the entire list. +# Resolver Mapping Template Reference: +# https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html +demo_dS.create_resolver("QueryGetDemosResolver", + type_name="Query", + field_name="getDemos", + request_mapping_template=appsync.MappingTemplate.dynamo_db_scan_table(), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_list() +) +# Resolver for the Mutation "addDemo" that puts the item into the DynamoDb table. +demo_dS.create_resolver("MutationAddDemoResolver", + type_name="Mutation", + field_name="addDemo", + request_mapping_template=appsync.MappingTemplate.dynamo_db_put_item( + appsync.PrimaryKey.partition("id").auto(), + appsync.Values.projecting("input")), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_item() +) +# To enable DynamoDB read consistency with the `MappingTemplate`: +demo_dS.create_resolver("QueryGetDemosConsistentResolver", + type_name="Query", + field_name="getDemosConsistent", + request_mapping_template=appsync.MappingTemplate.dynamo_db_scan_table(True), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_list() +) +``` +### Aurora Serverless +AppSync provides a data source for executing SQL commands against Amazon Aurora +Serverless clusters. You can use AppSync resolvers to execute SQL statements +against the Data API with GraphQL queries, mutations, and subscriptions. +```python +# Build a data source for AppSync to access the database. +# api: appsync.GraphqlApi +# Create username and password secret for DB Cluster +secret = rds.DatabaseSecret(self, "AuroraSecret", + username="clusteradmin" +) +# The VPC to place the cluster in +vpc = ec2.Vpc(self, "AuroraVpc") +# Create the serverless cluster, provide all values needed to customise the database. +cluster = rds.ServerlessCluster(self, "AuroraCluster", + engine=rds.DatabaseClusterEngine.AURORA_MYSQL, + vpc=vpc, + credentials={"username": "clusteradmin"}, + cluster_identifier="db-endpoint-test", + default_database_name="demos" +) +rds_dS = api.add_rds_data_source("rds", cluster, secret, "demos") +# Set up a resolver for an RDS query. +rds_dS.create_resolver("QueryGetDemosRdsResolver", + type_name="Query", + field_name="getDemosRds", + request_mapping_template=appsync.MappingTemplate.from_string(""" + { + "version": "2018-05-29", + "statements": [ + "SELECT * FROM demos" + ] + } + """), + response_mapping_template=appsync.MappingTemplate.from_string(""" + $utils.toJson($utils.rds.toJsonObject($ctx.result)[0]) + """) +) +# Set up a resolver for an RDS mutation. +rds_dS.create_resolver("MutationAddDemoRdsResolver", + type_name="Mutation", + field_name="addDemoRds", + request_mapping_template=appsync.MappingTemplate.from_string(""" + { + "version": "2018-05-29", + "statements": [ + "INSERT INTO demos VALUES (:id, :version)", + "SELECT * WHERE id = :id" + ], + "variableMap": { + ":id": $util.toJson($util.autoId()), + ":version": $util.toJson($ctx.args.version) + } + } + """), + response_mapping_template=appsync.MappingTemplate.from_string(""" + $utils.toJson($utils.rds.toJsonObject($ctx.result)[1][0]) + """) +) +``` +### HTTP Endpoints +GraphQL schema file `schema.graphql`: +```gql +type job { + id: String! + version: String! +} +input DemoInput { + version: String! +} +type Mutation { + callStepFunction(input: DemoInput!): job +} +``` +GraphQL request mapping template `request.vtl`: +```json +{ + "version": "2018-05-29", + "method": "POST", + "resourcePath": "/", + "params": { + "headers": { + "content-type": "application/x-amz-json-1.0", + "x-amz-target":"AWSStepFunctions.StartExecution" + }, + "body": { + "stateMachineArn": "<your step functions arn>", + "input": "{ \"id\": \"$context.arguments.id\" }" + } + } +} +``` +GraphQL response mapping template `response.vtl`: +```json +{ + "id": "${context.result.id}" +} +``` +CDK stack file `app-stack.ts`: +```python +api = appsync.GraphqlApi(self, "api", + name="api", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphql")) +) +http_ds = api.add_http_data_source("ds", "https://states.amazonaws.com", + name="httpDsWithStepF", + description="from appsync to StepFunctions Workflow", + authorization_config=appsync.AwsIamConfig( + signing_region="us-east-1", + signing_service_name="states" + ) +) +http_ds.create_resolver("MutationCallStepFunctionResolver", + type_name="Mutation", + field_name="callStepFunction", + request_mapping_template=appsync.MappingTemplate.from_file("request.vtl"), + response_mapping_template=appsync.MappingTemplate.from_file("response.vtl") +) +``` +### Amazon OpenSearch Service +AppSync has builtin support for Amazon OpenSearch Service (successor to Amazon +Elasticsearch Service) from domains that are provisioned through your AWS account. You can +use AppSync resolvers to perform GraphQL operations such as queries, mutations, and +subscriptions. +```python +import aws_cdk.aws_opensearchservice as opensearch +# api: appsync.GraphqlApi +user = iam.User(self, "User") +domain = opensearch.Domain(self, "Domain", + version=opensearch.EngineVersion.OPENSEARCH_1_3, + removal_policy=RemovalPolicy.DESTROY, + fine_grained_access_control=opensearch.AdvancedSecurityOptions(master_user_arn=user.user_arn), + encryption_at_rest=opensearch.EncryptionAtRestOptions(enabled=True), + node_to_node_encryption=True, + enforce_https=True +) +ds = api.add_open_search_data_source("ds", domain) +ds.create_resolver("QueryGetTestsResolver", + type_name="Query", + field_name="getTests", + request_mapping_template=appsync.MappingTemplate.from_string(JSON.stringify({ + "version": "2017-02-28", + "operation": "GET", + "path": "/id/post/_search", + "params": { + "headers": {}, + "query_string": {}, + "body": {"from": 0, "size": 50} + } + })), + response_mapping_template=appsync.MappingTemplate.from_string("""[ + #foreach($entry in $context.result.hits.hits) + #if( $velocityCount > 1 ) , #end + $utils.toJson($entry.get("_source")) + #end + ]""") +) +``` +## Custom Domain Names +For many use cases you may want to associate a custom domain name with your +GraphQL API. This can be done during the API creation. +```python +import aws_cdk.aws_certificatemanager as acm +import aws_cdk.aws_route53 as route53 +# hosted zone and route53 features +# hosted_zone_id: str +zone_name = "example.com" +my_domain_name = "api.example.com" +certificate = acm.Certificate(self, "cert", domain_name=my_domain_name) +schema = appsync.SchemaFile(file_path="mySchemaFile") +api = appsync.GraphqlApi(self, "api", + name="myApi", + schema=schema, + domain_name=appsync.DomainOptions( + certificate=certificate, + domain_name=my_domain_name + ) +) +# hosted zone for adding appsync domain +zone = route53.HostedZone.from_hosted_zone_attributes(self, "HostedZone", + hosted_zone_id=hosted_zone_id, + zone_name=zone_name +) +# create a cname to the appsync domain. will map to something like xxxx.cloudfront.net +route53.CnameRecord(self, "CnameApiRecord", + record_name="api", + zone=zone, + domain_name=api.app_sync_domain_name +) +``` +## Log Group +AppSync automatically create a log group with the name `/aws/appsync/apis/<graphql_api_id>` upon deployment with +log data set to never expire. If you want to set a different expiration period, use the `logConfig.retention` property. +To obtain the GraphQL API's log group as a `logs.ILogGroup` use the `logGroup` property of the +`GraphqlApi` construct. +```python +import aws_cdk.aws_logs as logs +log_config = appsync.LogConfig( + retention=logs.RetentionDays.ONE_WEEK +) +appsync.GraphqlApi(self, "api", + authorization_config=appsync.AuthorizationConfig(), + name="myApi", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "myApi.graphql")), + log_config=log_config +) +``` +## Schema +You can define a schema using from a local file using `SchemaFile.fromAsset` +```python +api = appsync.GraphqlApi(self, "api", + name="myApi", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphl")) +) +``` +### ISchema +Alternative schema sources can be defined by implementing the `ISchema` +interface. An example of this is the `CodeFirstSchema` class provided in +[awscdk-appsync-utils](https://github.com/cdklabs/awscdk-appsync-utils) +## Imports +Any GraphQL Api that has been created outside the stack can be imported from +another stack into your CDK app. Utilizing the `fromXxx` function, you have +the ability to add data sources and resolvers through a `IGraphqlApi` interface. +```python +# api: appsync.GraphqlApi +# table: dynamodb.Table +imported_api = appsync.GraphqlApi.from_graphql_api_attributes(self, "IApi", + graphql_api_id=api.api_id, + graphql_api_arn=api.arn +) +imported_api.add_dynamo_db_data_source("TableDataSource", table) +``` +If you don't specify `graphqlArn` in `fromXxxAttributes`, CDK will autogenerate +the expected `arn` for the imported api, given the `apiId`. For creating data +sources and resolvers, an `apiId` is sufficient. +## Authorization +There are multiple authorization types available for GraphQL API to cater to different +access use cases. They are: +* API Keys (`AuthorizationType.API_KEY`) +* Amazon Cognito User Pools (`AuthorizationType.USER_POOL`) +* OpenID Connect (`AuthorizationType.OPENID_CONNECT`) +* AWS Identity and Access Management (`AuthorizationType.AWS_IAM`) +* AWS Lambda (`AuthorizationType.AWS_LAMBDA`) +These types can be used simultaneously in a single API, allowing different types of clients to +access data. When you specify an authorization type, you can also specify the corresponding +authorization mode to finish defining your authorization. For example, this is a GraphQL API +with AWS Lambda Authorization. +```python +import aws_cdk.aws_lambda as lambda_ +# auth_function: lambda.Function +appsync.GraphqlApi(self, "api", + name="api", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "appsync.test.graphql")), + authorization_config=appsync.AuthorizationConfig( + default_authorization=appsync.AuthorizationMode( + authorization_type=appsync.AuthorizationType.LAMBDA, + lambda_authorizer_config=appsync.LambdaAuthorizerConfig( + handler=auth_function + ) + ) + ) +) +``` +## Permissions +When using `AWS_IAM` as the authorization type for GraphQL API, an IAM Role +with correct permissions must be used for access to API. +When configuring permissions, you can specify specific resources to only be +accessible by `IAM` authorization. For example, if you want to only allow mutability +for `IAM` authorized access you would configure the following. +In `schema.graphql`: +```gql +type Mutation { + updateExample(...): ... + @aws_iam +} +``` +In `IAM`: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "appsync:GraphQL" + ], + "Resource": [ + "arn:aws:appsync:REGION:ACCOUNT_ID:apis/GRAPHQL_ID/types/Mutation/fields/updateExample" + ] + } + ] +} +``` +See [documentation](https://docs.aws.amazon.com/appsync/latest/devguide/security.html#aws-iam-authorization) for more details. +To make this easier, CDK provides `grant` API. +Use the `grant` function for more granular authorization. +```python +# api: appsync.GraphqlApi +role = iam.Role(self, "Role", + assumed_by=iam.ServicePrincipal("lambda.amazonaws.com") +) +api.grant(role, appsync.IamResource.custom("types/Mutation/fields/updateExample"), "appsync:GraphQL") +``` +### IamResource +In order to use the `grant` functions, you need to use the class `IamResource`. +* `IamResource.custom(...arns)` permits custom ARNs and requires an argument. +* `IamResouce.ofType(type, ...fields)` permits ARNs for types and their fields. +* `IamResource.all()` permits ALL resources. +### Generic Permissions +Alternatively, you can use more generic `grant` functions to accomplish the same usage. +These include: +* grantMutation (use to grant access to Mutation fields) +* grantQuery (use to grant access to Query fields) +* grantSubscription (use to grant access to Subscription fields) +```python +# api: appsync.GraphqlApi +# role: iam.Role +# For generic types +api.grant_mutation(role, "updateExample") +# For custom types and granular design +api.grant(role, appsync.IamResource.of_type("Mutation", "updateExample"), "appsync:GraphQL") +``` +## Pipeline Resolvers and AppSync Functions +AppSync Functions are local functions that perform certain operations onto a +backend data source. Developers can compose operations (Functions) and execute +them in sequence with Pipeline Resolvers. +```python +# api: appsync.GraphqlApi +appsync_function = appsync.AppsyncFunction(self, "function", + name="appsync_function", + api=api, + data_source=api.add_none_data_source("none"), + request_mapping_template=appsync.MappingTemplate.from_file("request.vtl"), + response_mapping_template=appsync.MappingTemplate.from_file("response.vtl") +) +``` +AppSync Functions are used in tandem with pipeline resolvers to compose multiple +operations. +```python +# api: appsync.GraphqlApi +# appsync_function: appsync.AppsyncFunction +pipeline_resolver = appsync.Resolver(self, "pipeline", + api=api, + data_source=api.add_none_data_source("none"), + type_name="typeName", + field_name="fieldName", + request_mapping_template=appsync.MappingTemplate.from_file("beforeRequest.vtl"), + pipeline_config=[appsync_function], + response_mapping_template=appsync.MappingTemplate.from_file("afterResponse.vtl") +) +``` +Learn more about Pipeline Resolvers and AppSync Functions [here](https://docs.aws.amazon.com/appsync/latest/devguide/pipeline-resolvers.html). + +%package help +Summary: Development documents and examples for aws-cdk.aws-appsync-alpha +Provides: python3-aws-cdk.aws-appsync-alpha-doc +%description help +<!--END STABILITY BANNER--> +The `@aws-cdk/aws-appsync` package contains constructs for building flexible +APIs that use GraphQL. +```python +import aws_cdk.aws_appsync_alpha as appsync +``` +## Example +### DynamoDB +Example of a GraphQL API with `AWS_IAM` [authorization](#authorization) resolving into a DynamoDb +backend data source. +GraphQL schema file `schema.graphql`: +```gql +type demo { + id: String! + version: String! +} +type Query { + getDemos: [ demo! ] +} +input DemoInput { + version: String! +} +type Mutation { + addDemo(input: DemoInput!): demo +} +``` +CDK stack file `app-stack.ts`: +```python +api = appsync.GraphqlApi(self, "Api", + name="demo", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphql")), + authorization_config=appsync.AuthorizationConfig( + default_authorization=appsync.AuthorizationMode( + authorization_type=appsync.AuthorizationType.IAM + ) + ), + xray_enabled=True +) +demo_table = dynamodb.Table(self, "DemoTable", + partition_key=dynamodb.Attribute( + name="id", + type=dynamodb.AttributeType.STRING + ) +) +demo_dS = api.add_dynamo_db_data_source("demoDataSource", demo_table) +# Resolver for the Query "getDemos" that scans the DynamoDb table and returns the entire list. +# Resolver Mapping Template Reference: +# https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html +demo_dS.create_resolver("QueryGetDemosResolver", + type_name="Query", + field_name="getDemos", + request_mapping_template=appsync.MappingTemplate.dynamo_db_scan_table(), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_list() +) +# Resolver for the Mutation "addDemo" that puts the item into the DynamoDb table. +demo_dS.create_resolver("MutationAddDemoResolver", + type_name="Mutation", + field_name="addDemo", + request_mapping_template=appsync.MappingTemplate.dynamo_db_put_item( + appsync.PrimaryKey.partition("id").auto(), + appsync.Values.projecting("input")), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_item() +) +# To enable DynamoDB read consistency with the `MappingTemplate`: +demo_dS.create_resolver("QueryGetDemosConsistentResolver", + type_name="Query", + field_name="getDemosConsistent", + request_mapping_template=appsync.MappingTemplate.dynamo_db_scan_table(True), + response_mapping_template=appsync.MappingTemplate.dynamo_db_result_list() +) +``` +### Aurora Serverless +AppSync provides a data source for executing SQL commands against Amazon Aurora +Serverless clusters. You can use AppSync resolvers to execute SQL statements +against the Data API with GraphQL queries, mutations, and subscriptions. +```python +# Build a data source for AppSync to access the database. +# api: appsync.GraphqlApi +# Create username and password secret for DB Cluster +secret = rds.DatabaseSecret(self, "AuroraSecret", + username="clusteradmin" +) +# The VPC to place the cluster in +vpc = ec2.Vpc(self, "AuroraVpc") +# Create the serverless cluster, provide all values needed to customise the database. +cluster = rds.ServerlessCluster(self, "AuroraCluster", + engine=rds.DatabaseClusterEngine.AURORA_MYSQL, + vpc=vpc, + credentials={"username": "clusteradmin"}, + cluster_identifier="db-endpoint-test", + default_database_name="demos" +) +rds_dS = api.add_rds_data_source("rds", cluster, secret, "demos") +# Set up a resolver for an RDS query. +rds_dS.create_resolver("QueryGetDemosRdsResolver", + type_name="Query", + field_name="getDemosRds", + request_mapping_template=appsync.MappingTemplate.from_string(""" + { + "version": "2018-05-29", + "statements": [ + "SELECT * FROM demos" + ] + } + """), + response_mapping_template=appsync.MappingTemplate.from_string(""" + $utils.toJson($utils.rds.toJsonObject($ctx.result)[0]) + """) +) +# Set up a resolver for an RDS mutation. +rds_dS.create_resolver("MutationAddDemoRdsResolver", + type_name="Mutation", + field_name="addDemoRds", + request_mapping_template=appsync.MappingTemplate.from_string(""" + { + "version": "2018-05-29", + "statements": [ + "INSERT INTO demos VALUES (:id, :version)", + "SELECT * WHERE id = :id" + ], + "variableMap": { + ":id": $util.toJson($util.autoId()), + ":version": $util.toJson($ctx.args.version) + } + } + """), + response_mapping_template=appsync.MappingTemplate.from_string(""" + $utils.toJson($utils.rds.toJsonObject($ctx.result)[1][0]) + """) +) +``` +### HTTP Endpoints +GraphQL schema file `schema.graphql`: +```gql +type job { + id: String! + version: String! +} +input DemoInput { + version: String! +} +type Mutation { + callStepFunction(input: DemoInput!): job +} +``` +GraphQL request mapping template `request.vtl`: +```json +{ + "version": "2018-05-29", + "method": "POST", + "resourcePath": "/", + "params": { + "headers": { + "content-type": "application/x-amz-json-1.0", + "x-amz-target":"AWSStepFunctions.StartExecution" + }, + "body": { + "stateMachineArn": "<your step functions arn>", + "input": "{ \"id\": \"$context.arguments.id\" }" + } + } +} +``` +GraphQL response mapping template `response.vtl`: +```json +{ + "id": "${context.result.id}" +} +``` +CDK stack file `app-stack.ts`: +```python +api = appsync.GraphqlApi(self, "api", + name="api", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphql")) +) +http_ds = api.add_http_data_source("ds", "https://states.amazonaws.com", + name="httpDsWithStepF", + description="from appsync to StepFunctions Workflow", + authorization_config=appsync.AwsIamConfig( + signing_region="us-east-1", + signing_service_name="states" + ) +) +http_ds.create_resolver("MutationCallStepFunctionResolver", + type_name="Mutation", + field_name="callStepFunction", + request_mapping_template=appsync.MappingTemplate.from_file("request.vtl"), + response_mapping_template=appsync.MappingTemplate.from_file("response.vtl") +) +``` +### Amazon OpenSearch Service +AppSync has builtin support for Amazon OpenSearch Service (successor to Amazon +Elasticsearch Service) from domains that are provisioned through your AWS account. You can +use AppSync resolvers to perform GraphQL operations such as queries, mutations, and +subscriptions. +```python +import aws_cdk.aws_opensearchservice as opensearch +# api: appsync.GraphqlApi +user = iam.User(self, "User") +domain = opensearch.Domain(self, "Domain", + version=opensearch.EngineVersion.OPENSEARCH_1_3, + removal_policy=RemovalPolicy.DESTROY, + fine_grained_access_control=opensearch.AdvancedSecurityOptions(master_user_arn=user.user_arn), + encryption_at_rest=opensearch.EncryptionAtRestOptions(enabled=True), + node_to_node_encryption=True, + enforce_https=True +) +ds = api.add_open_search_data_source("ds", domain) +ds.create_resolver("QueryGetTestsResolver", + type_name="Query", + field_name="getTests", + request_mapping_template=appsync.MappingTemplate.from_string(JSON.stringify({ + "version": "2017-02-28", + "operation": "GET", + "path": "/id/post/_search", + "params": { + "headers": {}, + "query_string": {}, + "body": {"from": 0, "size": 50} + } + })), + response_mapping_template=appsync.MappingTemplate.from_string("""[ + #foreach($entry in $context.result.hits.hits) + #if( $velocityCount > 1 ) , #end + $utils.toJson($entry.get("_source")) + #end + ]""") +) +``` +## Custom Domain Names +For many use cases you may want to associate a custom domain name with your +GraphQL API. This can be done during the API creation. +```python +import aws_cdk.aws_certificatemanager as acm +import aws_cdk.aws_route53 as route53 +# hosted zone and route53 features +# hosted_zone_id: str +zone_name = "example.com" +my_domain_name = "api.example.com" +certificate = acm.Certificate(self, "cert", domain_name=my_domain_name) +schema = appsync.SchemaFile(file_path="mySchemaFile") +api = appsync.GraphqlApi(self, "api", + name="myApi", + schema=schema, + domain_name=appsync.DomainOptions( + certificate=certificate, + domain_name=my_domain_name + ) +) +# hosted zone for adding appsync domain +zone = route53.HostedZone.from_hosted_zone_attributes(self, "HostedZone", + hosted_zone_id=hosted_zone_id, + zone_name=zone_name +) +# create a cname to the appsync domain. will map to something like xxxx.cloudfront.net +route53.CnameRecord(self, "CnameApiRecord", + record_name="api", + zone=zone, + domain_name=api.app_sync_domain_name +) +``` +## Log Group +AppSync automatically create a log group with the name `/aws/appsync/apis/<graphql_api_id>` upon deployment with +log data set to never expire. If you want to set a different expiration period, use the `logConfig.retention` property. +To obtain the GraphQL API's log group as a `logs.ILogGroup` use the `logGroup` property of the +`GraphqlApi` construct. +```python +import aws_cdk.aws_logs as logs +log_config = appsync.LogConfig( + retention=logs.RetentionDays.ONE_WEEK +) +appsync.GraphqlApi(self, "api", + authorization_config=appsync.AuthorizationConfig(), + name="myApi", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "myApi.graphql")), + log_config=log_config +) +``` +## Schema +You can define a schema using from a local file using `SchemaFile.fromAsset` +```python +api = appsync.GraphqlApi(self, "api", + name="myApi", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "schema.graphl")) +) +``` +### ISchema +Alternative schema sources can be defined by implementing the `ISchema` +interface. An example of this is the `CodeFirstSchema` class provided in +[awscdk-appsync-utils](https://github.com/cdklabs/awscdk-appsync-utils) +## Imports +Any GraphQL Api that has been created outside the stack can be imported from +another stack into your CDK app. Utilizing the `fromXxx` function, you have +the ability to add data sources and resolvers through a `IGraphqlApi` interface. +```python +# api: appsync.GraphqlApi +# table: dynamodb.Table +imported_api = appsync.GraphqlApi.from_graphql_api_attributes(self, "IApi", + graphql_api_id=api.api_id, + graphql_api_arn=api.arn +) +imported_api.add_dynamo_db_data_source("TableDataSource", table) +``` +If you don't specify `graphqlArn` in `fromXxxAttributes`, CDK will autogenerate +the expected `arn` for the imported api, given the `apiId`. For creating data +sources and resolvers, an `apiId` is sufficient. +## Authorization +There are multiple authorization types available for GraphQL API to cater to different +access use cases. They are: +* API Keys (`AuthorizationType.API_KEY`) +* Amazon Cognito User Pools (`AuthorizationType.USER_POOL`) +* OpenID Connect (`AuthorizationType.OPENID_CONNECT`) +* AWS Identity and Access Management (`AuthorizationType.AWS_IAM`) +* AWS Lambda (`AuthorizationType.AWS_LAMBDA`) +These types can be used simultaneously in a single API, allowing different types of clients to +access data. When you specify an authorization type, you can also specify the corresponding +authorization mode to finish defining your authorization. For example, this is a GraphQL API +with AWS Lambda Authorization. +```python +import aws_cdk.aws_lambda as lambda_ +# auth_function: lambda.Function +appsync.GraphqlApi(self, "api", + name="api", + schema=appsync.SchemaFile.from_asset(path.join(__dirname, "appsync.test.graphql")), + authorization_config=appsync.AuthorizationConfig( + default_authorization=appsync.AuthorizationMode( + authorization_type=appsync.AuthorizationType.LAMBDA, + lambda_authorizer_config=appsync.LambdaAuthorizerConfig( + handler=auth_function + ) + ) + ) +) +``` +## Permissions +When using `AWS_IAM` as the authorization type for GraphQL API, an IAM Role +with correct permissions must be used for access to API. +When configuring permissions, you can specify specific resources to only be +accessible by `IAM` authorization. For example, if you want to only allow mutability +for `IAM` authorized access you would configure the following. +In `schema.graphql`: +```gql +type Mutation { + updateExample(...): ... + @aws_iam +} +``` +In `IAM`: +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "appsync:GraphQL" + ], + "Resource": [ + "arn:aws:appsync:REGION:ACCOUNT_ID:apis/GRAPHQL_ID/types/Mutation/fields/updateExample" + ] + } + ] +} +``` +See [documentation](https://docs.aws.amazon.com/appsync/latest/devguide/security.html#aws-iam-authorization) for more details. +To make this easier, CDK provides `grant` API. +Use the `grant` function for more granular authorization. +```python +# api: appsync.GraphqlApi +role = iam.Role(self, "Role", + assumed_by=iam.ServicePrincipal("lambda.amazonaws.com") +) +api.grant(role, appsync.IamResource.custom("types/Mutation/fields/updateExample"), "appsync:GraphQL") +``` +### IamResource +In order to use the `grant` functions, you need to use the class `IamResource`. +* `IamResource.custom(...arns)` permits custom ARNs and requires an argument. +* `IamResouce.ofType(type, ...fields)` permits ARNs for types and their fields. +* `IamResource.all()` permits ALL resources. +### Generic Permissions +Alternatively, you can use more generic `grant` functions to accomplish the same usage. +These include: +* grantMutation (use to grant access to Mutation fields) +* grantQuery (use to grant access to Query fields) +* grantSubscription (use to grant access to Subscription fields) +```python +# api: appsync.GraphqlApi +# role: iam.Role +# For generic types +api.grant_mutation(role, "updateExample") +# For custom types and granular design +api.grant(role, appsync.IamResource.of_type("Mutation", "updateExample"), "appsync:GraphQL") +``` +## Pipeline Resolvers and AppSync Functions +AppSync Functions are local functions that perform certain operations onto a +backend data source. Developers can compose operations (Functions) and execute +them in sequence with Pipeline Resolvers. +```python +# api: appsync.GraphqlApi +appsync_function = appsync.AppsyncFunction(self, "function", + name="appsync_function", + api=api, + data_source=api.add_none_data_source("none"), + request_mapping_template=appsync.MappingTemplate.from_file("request.vtl"), + response_mapping_template=appsync.MappingTemplate.from_file("response.vtl") +) +``` +AppSync Functions are used in tandem with pipeline resolvers to compose multiple +operations. +```python +# api: appsync.GraphqlApi +# appsync_function: appsync.AppsyncFunction +pipeline_resolver = appsync.Resolver(self, "pipeline", + api=api, + data_source=api.add_none_data_source("none"), + type_name="typeName", + field_name="fieldName", + request_mapping_template=appsync.MappingTemplate.from_file("beforeRequest.vtl"), + pipeline_config=[appsync_function], + response_mapping_template=appsync.MappingTemplate.from_file("afterResponse.vtl") +) +``` +Learn more about Pipeline Resolvers and AppSync Functions [here](https://docs.aws.amazon.com/appsync/latest/devguide/pipeline-resolvers.html). + +%prep +%autosetup -n aws-cdk.aws-appsync-alpha-2.59.0a0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-aws-cdk.aws-appsync-alpha -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Wed May 31 2023 Python_Bot <Python_Bot@openeuler.org> - 2.59.0a0-1 +- Package Spec generated |