Learn - amazon dynamodb

A

Preparations

Before using the plugin an AWS account must be created and the security credentials must be retrieved.
1

AWS Sign up

Everything you need to know about AWS can be found here. Before you start using this plugin sign up and go through the "Getting started with AWS in under 15 minutes"
2

Getting Your Access Key ID and Secret Access Key

There is basically two ways to get the access key ID and secret access key. Either through the Security Credentials page for your AWS user or create a user through the IAM Manager and get the keys for that specific user. Adding a new user for your game (e.g. MyAwesomeGameUser) is recommended rather than using the keys for your main AWS user.

Goto http://docs.aws.amazon.com/general/latest/gr/getting-aws-sec-creds.html to find out more on how to setup and handle security credentials.

Important, you should also read the IAM Best Practices
B

Dynamo DB Utility

The DynamoDBUtility class makes it easier to use DynamoDB. The class is created as a state machine and is designed with the idea that you shouldn't be able to use the methods unless it's initialized and ready to use.
1

Adding the Utility as a Component

DynamoDB_1First step is adding the Utility as a component to a new game object.
2

Setting up a test class

For the purpose of this tutorial, we'll create a new script called DynamoDBTestingScript and attach it to the same game object as the DynamoDBUtility component. We'll start by creating a reference to the utility as one of the members along with your use account settings for AWS.
public class DynamoDBTest : MonoBehaviour
{
	public string		m_accessKey			= "INSERT_ACCESS_KEY_HERE";
	public string		m_secretKey			= "INSERT_SECRET_KEY_HERE";
	public EAWSRegion	m_region			= EAWSRegion.USEast1;
	DynamoDBUtility		m_dbService			= null;

	void Awake()
	{
		//This only works if the utility is attached to the same gameobject as
		//this script. Otherwise you need to reference it either publicly or through a method.
		m_dbService = GetComponent<DynamoDBUtility>();

		// Do not initialize in awake
	}
}
3

Initializing the utility class

Pass in the access key, secret key and the operating region to the initialize method to initialize the Amazon DynamoDB Utility. All the methods in our AWS library are operating asynchronously, so before you're using any other method you need to wait for the IsInitialized property to be set to true.
void OnGUI()
{
	if(!m_dbService.IsInitialized)
	{
		if(GUILayout.Button("Initialize", GUILayout.MinHeight(Screen.height * 0.2f), GUILayout.Width(Screen.width * 0.45f)))
			m_dbService.Initialize(m_accessKey, m_secretKey, m_region);
	}
}
C

Code Examples

1

Creating a table

void CreateTable()
{
	CreateTableRequest tableRequest = new CreateTableRequest();
	tableRequest.TableName = "MY_TABLE_NAME";

	AttributeDefinition definition = new AttributeDefinition();
	definition.AttributeName = "MY_ATTRIBUTE_NAME";
	definition.AttributeType = ScalarAttributeType.S;
	tableRequest.AttributeDefinitions.Add(definition);

	ProvisionedThroughput throughput = new ProvisionedThroughput();
	throughput.ReadCapacityUnits = 3;
	throughput.WriteCapacityUnits = 1;
	tableRequest.ProvisionedThroughput = throughput;

	KeySchemaElement element = new KeySchemaElement();
	//specify which attribute(s) to act as the key for the table 
	element.AttributeName = "MY_ATTRIBUTE_NAME";
	element.KeyType = KeyType.HASH;
	tableRequest.KeySchema.Add(keySchema);

	m_dbService.CreateTable(tableRequest, OnCreatedTable);
}

//event handler
void OnCreatedTable(bool success, string tableName, CreateTableResponse response)
{
	if(success)
		Debug.Log(tableName + " was created successfully!");
	else
		Debug.LogError("Failed to create " + tableName + "!");
}
2

Updating a table

void UpdateTable()
{
	UpdateTableRequest updateTable = new UpdateTableRequest();
	updateTable.TableName = "MY_UNIQUE_TABLE_NAME";

	ProvisionedThroughput throughput = new ProvisionedThroughput();
	throughput.ReadCapacityUnits = 1;
	throughput.WriteCapacityUnits = 1;
	updateTable.ProvisionedThroughput = throughput;
	m_dbService.UpdateTable(updateTable, OnUpdatedTable);
}

//event handler
void OnUpdatedTable(bool success, string tableName, UpdateTableResponse response)
{
	if(success)
		Debug.Log("Successfully updated table: " + tableName + "!");
	else
		Debug.LogError("Failed to to update table: " + tableName + "!");
}
3

Adding an object to a table

void CreateItem()
{
	PutItemRequest putRequest = new PutItemRequest();
	putRequest.TableName = "MY_UNIQUE_TABLE_NAME";

	AttributeValue attributeVal = new AttributeValue();
	//S = String value
	attributeVal.S = "MY_ATTRIBUTE_VALUE";
	//add the new value to an attribute value that exist in the table.
	putRequest.Item.Add("MY_ATTRIBUTE_NAME", attributeVal);

	m_dbService.CreateItem(putRequest, OnCreatedItem);
}

//event handler
void OnCreatedItem(bool success, string tableName, PutItemResult itemResult)
{
	if(success)
		Debug.Log("Successfully created an item in table: " + tableName);
	else
		Debug.LogError("Failed to to create an item in table: " + tableName);
}
4

Scanning a table

void ScanTable()
{
	ScanRequest scanRequest = new ScanRequest();
	scanRequest.TableName = "MY_UNIQUE_TABLE_NAME";
	m_dbService.Scan(scanRequest, OnScan);
}

//event handler
void OnScan(bool success, ScanResult result)
{
	if(success)
	{
		Debug.Log("Successfully scanned table!");
		foreach(var dictionary in result.Items)
		{
			foreach(var pair in dictionary)
				Debug.Log("Attribute: " + pair.Key);
		}
	}
	else
	{
		Debug.LogError("Failed to scan table!");
	}
}
5

Querying a table

void QueryTable()
{
	QueryRequest queryRequest = new QueryRequest();
	queryRequest.TableName = "MY_UNIQUE_TABLE_NAME";

	Condition myQueryCondition = new Condition();
	myQueryCondition.ComparisonOperator = ComparisonOperator.EQ;

	AttributeValue myQueryValue = new AttributeValue();
	myQueryValue.S = "MY_ATTRIBUTE_VALUE";

	myQueryCondition.AttributeValueList.Add(myQueryValue);

	queryRequest.KeyConditions.Add("MY_ATTRIBUTE_NAME", myQueryCondition);

	m_dbService.Query(queryRequest, OnQuery);
}

//event handler
void OnQuery(bool success, QueryResult result)
{
	if(success)
	{
		Debug.Log("Successfully queried table!");
		foreach(var dictionary in result.Items)
		{
			foreach(var pair in dictionary)
				Debug.Log("Attribute: " + pair.Key);
		}
	}
	else
	{
		Debug.LogError("Failed to query table!");
	}
}
D

Waiting for a table to be ready

Creating, Updating or Deleting a table does not happen instantly. For example, when you create a table with DynamoDB you will get a response if the operation was a success. The service will then create a table and set it to the active status "CREATING". You are not allowed to operate on the table unless the status equals "ACTIVE".

The DynamoDBUtility will do this waiting automatically for you when creating and updating a table, but it will not wait forever. How many times it will poll the table status is governed by the properties "DescribeTableWaitTime" and "MaxDescribeTableCount". The table will stop waiting if these values are exceeded or if an error occurred.

If this would be the case, you can continue waiting for the active state of the table by using the method WaitUntilTableIsReady().
void WaitForActiveStatus()
{
	m_dbService.WaitUntilTableIsReady("MY_UNIQUE_TABLE_NAME", (bool isActive) =>
	{
		if(isActive)
			Debug.Log("The table is ACTIVE");
		else 
			Debug.LogError("The table failed to wait for ACTIVE status");
	});
}
E

Using Amazon Dynamo in editor scripts

You can't use the DynamoDBUtility class if you want to use DynamoDB in an editor extension or an editor script. The utility class relies heavily on Update() and the time structure used at runtime.

To use the methods in the editor, we recommend you to use our .NET interface class called NETDynamoDB.

NOTE: You will have to keep track of the initialization, completion as well as the order of method executions by yourself when using NETDynamoDB.
public class MyEditorClass
{
	NETDynamoDB dynamoDB = null;

	public MyEditorClass()
	{
		dynamoDB = new NETDynamoDB();
	}

	public void Initialize(string accessKey, string secretKey, EAWSRegion region)
	{
		dynamoDB.Initialize(accessKey, secretKey, region, OnInitialize);
	}

	void OnInitialize(bool success)
	{
		if(success)
			Debug.Log("DynamoDB Initialized Successfully!");
		else
			Debug.LogError("Failed to Initialize DynamoDB!");
	}
}
F

Encryption of Access & Secret Access keys