View a markdown version of this page

Enhanced snapshot API examples - Managed Service for Apache Flink
Request examples

Enhanced snapshot API examples

Use the following examples to call the enhanced snapshot API actions. Each snapshot action example shows the full request and response. The CreateApplication and UpdateApplication examples show only the request. For information about how to use a JSON file for input for an API action, see Managed Service for Apache Flink API example code.

The examples use the account 111122223333, the Region aa-example-1, the application MyApplication, and the enhanced snapshot MyApplication-snapshot-1. Timestamps are in epoch seconds.

Request examples

Each of the following sections shows one API action.

Create an enhanced snapshot

The following example request for the CreateSnapshot action creates an enhanced snapshot of a running application:

{
    "ApplicationName": "MyApplication",
    "SnapshotName": "MyApplication-snapshot-1",
    "SnapshotDescription": "Before code update",
    "Tags": [ { "Key": "Environment", "Value": "prod" } ]
}

The following example shows the response:

{
    "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1",
    "SnapshotStatus": "CREATING",
    "SnapshotOperationId": "a1B2c3D4e5F6",
    "SnapshotOperationStatus": "IN_PROGRESS"
}

Describe an enhanced snapshot

The following example request for the DescribeSnapshot action returns the details of an enhanced snapshot:

{
    "SnapshotName": "MyApplication-snapshot-1"
}

The following example shows the response:

{
    "SnapshotInfoDetails": {
        "SnapshotName": "MyApplication-snapshot-1",
        "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1",
        "SnapshotDescription": "Before code update",
        "SnapshotStatus": "READY",
        "SnapshotCreationTimestamp": 1767225600,
        "RuntimeEnvironment": "FLINK-1_20",
        "SnapshotSizeInBytes": 104857600,
        "SnapshotEncryptionConfigurationDescription": {
            "KeyType": "AWS_OWNED_KEY"
        },
        "SnapshotInitiator": "USER",
        "SnapshotInitiatorOperation": "CreateSnapshot",
        "SnapshotSourceDescription": {
            "SourceApplicationDescription": {
                "ApplicationName": "MyApplication",
                "ApplicationCreationTimestamp": 1764547200,
                "ApplicationVersionId": 3
            }
        },
        "SnapshotFormat": "CANONICAL"
    }
}

List the enhanced snapshots in an account

The following example request for the ListSnapshots action lists the enhanced snapshots in the account and Region.

All filter fields are optional. The request accepts at most one of these filter fields: SourceApplicationName, SnapshotInitiator, SnapshotInitiatorOperation, or SnapshotStatus.

{
    "Limit": 50
}

The following example shows the response. The newest enhanced snapshot comes first.

{
    "SnapshotInfoList": [
        {
            "SnapshotName": "SYSTEMSNAPSHOT-STOP-MyApplication-1767312000000",
            "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/SYSTEMSNAPSHOT-STOP-MyApplication-1767312000000",
            "SnapshotStatus": "READY",
            "SnapshotCreationTimestamp": 1767312000,
            "SnapshotInitiator": "SYSTEM",
            "SnapshotInitiatorOperation": "SystemCreateSnapshot",
            "SourceApplicationName": "MyApplication",
            "SnapshotFormat": "CANONICAL"
        },
        {
            "SnapshotName": "MyApplication-snapshot-1",
            "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1",
            "SnapshotStatus": "READY",
            "SnapshotCreationTimestamp": 1767225600,
            "SnapshotInitiator": "USER",
            "SnapshotInitiatorOperation": "CreateSnapshot",
            "SourceApplicationName": "MyApplication",
            "SnapshotFormat": "CANONICAL"
        }
    ]
}

Delete an enhanced snapshot

The following example request for the DeleteSnapshot action deletes an enhanced snapshot. Copy the SnapshotCreationTimestamp value from the DescribeSnapshot response.

{
    "SnapshotName": "MyApplication-snapshot-1",
    "SnapshotCreationTimestamp": 1767225600
}

The following example shows the response:

{
    "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1",
    "SnapshotStatus": "DELETING",
    "SnapshotOperationId": "g7H8i9J0k1L2",
    "SnapshotOperationStatus": "IN_PROGRESS"
}

Import an enhanced snapshot

The following example request for the ImportSnapshot action imports an Apache Flink savepoint from Amazon S3 as a new enhanced snapshot:

{
    "SnapshotName": "MyApplication-snapshot-imported",
    "ImportSourceConfiguration": {
        "SourceType": "S3",
        "ImportRoleArn": "arn:aws:iam::111122223333:role/MSFSnapshotImportRole",
        "SourceS3PrefixLocation": {
            "BucketARN": "arn:aws:s3:::amzn-s3-demo-bucket",
            "KeyPrefix": "imports/my-app/"
        }
    },
    "DestinationEncryptionConfiguration": {
        "KeyId": "arn:aws:kms:aa-example-1:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "KeyType": "CUSTOMER_MANAGED_KEY"
    },
    "SnapshotDescription": "Imported from self-managed Apache Flink",
    "Tags": [ { "Key": "Environment", "Value": "prod" } ]
}

The following example shows the response:

{
    "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-imported",
    "SnapshotStatus": "CREATING",
    "SnapshotOperationId": "m3N4o5P6q7R8",
    "SnapshotOperationStatus": "IN_PROGRESS"
}

Export an enhanced snapshot

The following example request for the ExportSnapshot action exports an enhanced snapshot to an Amazon S3 bucket. DestinationEncryptionConfiguration is optional. If you omit it, Managed Service for Apache Flink uses AWS_OWNED_KEY.

{
    "SnapshotName": "MyApplication-snapshot-1",
    "ExportDestinationConfiguration": {
        "DestinationType": "S3",
        "ExportRoleArn": "arn:aws:iam::111122223333:role/MSFSnapshotExportRole",
        "DestinationEncryptionConfiguration": {
            "KeyType": "AWS_OWNED_KEY"
        },
        "DestinationS3PrefixLocation": {
            "BucketARN": "arn:aws:s3:::amzn-s3-demo-bucket",
            "KeyPrefix": "exports/my-app/"
        }
    }
}

The following example shows the response. The response has no snapshot ARN or snapshot status.

{
    "SnapshotOperationId": "s9T0u1V2w3X4",
    "SnapshotOperationStatus": "IN_PROGRESS"
}

Describe an enhanced snapshot operation

The following example request for the DescribeSnapshotOperation action returns the details of an export operation:

{
    "SnapshotName": "MyApplication-snapshot-1",
    "SnapshotOperationId": "s9T0u1V2w3X4"
}

The following example shows the response for a successful export. The ExportedPrefix field holds the full path of the exported files.

{
    "SnapshotOperationInfoDetails": {
        "SnapshotOperationId": "s9T0u1V2w3X4",
        "SnapshotOperation": "ExportSnapshot",
        "SnapshotOperationStatus": "SUCCESSFUL",
        "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1",
        "DestinationEncryptionConfigurationDescription": {
            "KeyType": "AWS_OWNED_KEY"
        },
        "SnapshotDestinationLocationDescription": {
            "LocationType": "S3",
            "S3PrefixLocation": {
                "BucketARN": "arn:aws:s3:::amzn-s3-demo-bucket",
                "KeyPrefix": "exports/my-app/",
                "ExportedPrefix": "exports/my-app/s9T0u1V2w3X4/data/"
            }
        },
        "StartTime": 1767229200,
        "EndTime": 1767229800
    }
}

The following example shows the response for a failed export. The response adds SnapshotOperationFailureDetails. S3PrefixLocation also includes ExportedPrefix for a failed export.

{
    "SnapshotOperationInfoDetails": {
        "SnapshotOperationId": "y5Z6a7B8c9D0",
        "SnapshotOperation": "ExportSnapshot",
        "SnapshotOperationStatus": "FAILED",
        "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1",
        "DestinationEncryptionConfigurationDescription": {
            "KeyType": "AWS_OWNED_KEY"
        },
        "SnapshotDestinationLocationDescription": {
            "LocationType": "S3",
            "S3PrefixLocation": {
                "BucketARN": "arn:aws:s3:::amzn-s3-demo-bucket",
                "KeyPrefix": "exports/my-app/",
                "ExportedPrefix": "exports/my-app/y5Z6a7B8c9D0/data/"
            }
        },
        "StartTime": 1767232800,
        "EndTime": 1767233100,
        "SnapshotOperationFailureDetails": {
            "ErrorInfo": {
                "ErrorCode": "S3AccessDenied",
                "ErrorString": "..."
            }
        }
    }
}

List the operations of an enhanced snapshot

The following example request for the ListSnapshotOperations action lists the failed operations of an enhanced snapshot. The request accepts at most one of these filter fields: SnapshotOperation or SnapshotOperationStatus.

{
    "SnapshotName": "MyApplication-snapshot-1",
    "SnapshotOperationStatus": "FAILED",
    "Limit": 50
}

The following example shows the response:

{
    "SnapshotOperationInfoList": [
        {
            "SnapshotOperationId": "y5Z6a7B8c9D0",
            "SnapshotOperation": "ExportSnapshot",
            "SnapshotOperationStatus": "FAILED",
            "StartTime": 1767232800,
            "EndTime": 1767233100
        }
    ]
}

Create an application in enhanced snapshot mode

The following example request for the CreateApplication action creates an application in enhanced snapshot mode. Set SnapshotMode to ENHANCED_SNAPSHOTS. The request must include SnapshotsEnabled. Set SnapshotsEnabled to true to turn on system snapshots.

{
    "ApplicationName": "MyApplication",
    "RuntimeEnvironment": "FLINK-1_20",
    "ServiceExecutionRole": "arn:aws:iam::111122223333:role/MyApplicationServiceRole",
    "ApplicationConfiguration": {
        "ApplicationCodeConfiguration": {
            "CodeContent": {
                "S3ContentLocation": {
                    "BucketARN": "arn:aws:s3:::amzn-s3-demo-bucket",
                    "FileKey": "my-flink-app.jar"
                }
            },
            "CodeContentType": "ZIPFILE"
        },
        "ApplicationSnapshotConfiguration": {
            "SnapshotsEnabled": true,
            "SnapshotMode": "ENHANCED_SNAPSHOTS"
        }
    }
}

Upgrade an existing application to enhanced snapshot mode

The following example request for the UpdateApplication action upgrades an application to enhanced snapshot mode. The request must include SnapshotsEnabledUpdate together with SnapshotModeUpdate.

Note

You cannot set SnapshotModeUpdate back to APPLICATION_SNAPSHOTS_LEGACY. That request returns InvalidArgumentException. To return to application snapshots (legacy), call RollbackApplication when the upgrade is still the most recent update. For more information, see Upgrade an existing application to enhanced snapshots.

{
    "ApplicationName": "MyApplication",
    "CurrentApplicationVersionId": 3,
    "ApplicationConfigurationUpdate": {
        "ApplicationSnapshotConfigurationUpdate": {
            "SnapshotsEnabledUpdate": true,
            "SnapshotModeUpdate": "ENHANCED_SNAPSHOTS"
        }
    }
}

Start an application from an enhanced snapshot

The following example request for the StartApplication action starts an application from an enhanced snapshot. Set ApplicationRestoreType to RESTORE_FROM_CUSTOM_SNAPSHOT. Identify the enhanced snapshot with SnapshotArn, not SnapshotName.

{
    "ApplicationName": "MyApplication",
    "RunConfiguration": {
        "ApplicationRestoreConfiguration": {
            "ApplicationRestoreType": "RESTORE_FROM_CUSTOM_SNAPSHOT",
            "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"
        }
    }
}

The following example shows the response:

{
    "OperationId": "Abc123Def456"
}

Update an application and restore from an enhanced snapshot

The following example request for the UpdateApplication action restores a running application from an enhanced snapshot. The application must be in the RUNNING status.

{
    "ApplicationName": "MyApplication",
    "CurrentApplicationVersionId": 4,
    "RunConfigurationUpdate": {
        "ApplicationRestoreConfiguration": {
            "ApplicationRestoreType": "RESTORE_FROM_CUSTOM_SNAPSHOT",
            "SnapshotArn": "arn:aws:kinesisanalytics:aa-example-1:111122223333:snapshot/MyApplication-snapshot-1"
        }
    }
}

For more information, see Restore an application from an enhanced snapshot.