Version:

Icon of a magnifying glass.
  Edit on GitHub

IN THIS ARTICLE

Resource Mapping Files

A resource mapping file is a JSON file that provides a map of lookup names to a collection of attributes about AWS resources. O3DE runtimes can query the mapping file to easily find and utilize AWS resources. Typically, a project under development will use a different deployment, and therefore a different mapping file, than the released version of the project.

A mapping file contains one or more resource entries and a set of global attributes.

Resource entry format

Each entry defines a lookup name - a logical name for the resource - and a collection of attributes in the following format:

"<lookup name>":  {
    "Type": string, (required)
    "Name/ID": string, (required)
    "Region": string, (optional)
    "AccountId": string (optional)
}

Supported attributes

  • Type - AWS resource type, e.g. AWS::Lambda::Function, AWS::S3::Bucket etc. Should map to a CloudFormation resource type .
  • Name/ID - AWS resource name or id.
  • Region - Used to override the global region attribute, if this resource is deployed to a different AWS region.
  • AccountId - Used to override the global account id attribute, if this resource is deployed in a different AWS account.

Global attributes

The mapping file also supports one optional and two required global attributes:

  • AccountId (optional) - The default AWS account that is used to search for AWS resources referenced in your O3DE application code. Used when account ID is not otherwise explicitly referenced (such as on a specific resource mapping).
  • Region - The default region to use with this mapping file.
  • Version - The json schema version of this document.

Example of a complete mapping file

{
    "AWSResourceMappings": {
        "MyKey": {
            "Name/ID": "ExampleLambda",
            "Type": "AWS::Lambda::Function"
        }
    },
    "AccountId": "123456789123",
    "Region": "us-west-2",
    "Version": "1.0.0"
}

This mapping file has a single mapping: MyKey, which is a Lambda function called “ExampleLambda”. It is deployed in us-west-2 in the AWS account with account ID “123456789123”.

Important:
We strongly recommend against including your AWS account ID in builds distributed to untrusted environments. Depending on your use case, anonymous client authentication or the use of custom domains may provide ways of interacting with your AWS resources without needing to specify an account ID.

Generating a resource mappings file

The mapping files have a well-defined JSON format. They can be generated using custom tools or by hand. However, the easiest way to generate or edit these files is by using the visual resource mapping tool provided with O3DE.

All mapping files should be saved into the project’s Config directory.

Using resource mappings

Define the resource mapping file to use on load in the ResourceMappingConfigFileName setting in the awscoreconfiguration.setreg file, located in the project’s Registry directory. See Project Settings for more information about this file. The AWS Core Gem loads the defined mapping file on initialization and supports access to the mappings.

Use the request bus (AWSResourceMappingRequestBus) to interact with a configured resource mapping file. See AWSResourceMappingRequests for the class API reference for the bus.

Example: Reading an entry

// Read settings for a mapping entry called "MyTableKey".
AZStd::string requestTableName = "";
AWSResourceMappingRequestBus::BroadcastResult(requestTableName, &AWSResourceMappingRequests::GetResourceNameId, "MyTableKey");

AZStd::string requestRegion = "";
AWSResourceMappingRequestBus::BroadcastResult(requestRegion, &AWSResourceMappingRequests::GetResourceRegion, "MyTableKey");