Metadata

Metadata elements are custom, client provided key / value pairs that can be forwarded to application instances (e.g. a game server). The main purpose of this is for a Matchmaker to provide game server configuration values to be sent to a game server upon allocation of said game server.

In our system, Metadata elements are part of ApplicationInstance elements.

See the chapter about the matchmaker allocation process for more information.

Structure

Property	Value type	Required	Description
key	string	Yes	The name of the metadata entry
value	string	Yes	The value of the metadata entry

Table 1: Metadata element structure

Requirements

A Metadata element has the following constraints:

• allowed characters in the key are a-z 0-9 _ -

• the key may be no longer than 50 characters

• the value may be no longer than 150 characters

Manually adding & updating ApplicationInstance metadata

Metadata in the ApplicationInstance elements are stored as an array of Metadata elements:

PUT /applicationInstance/{applicationInstanceId}

{
  "metadata": [
    {
      "key": "metadata1",
      "value": "A value"
    },
    {
      "key": "metadata2",
      "value": "Another value"
    }
  ]
}

Figure 1: Example metadata for an ApplicationInstance element

When you want to add a new metadata element, you can PUT an element with only that new metadata element. You would submit:

PUT /applicationInstance/{applicationInstanceId}

{
  "metadata": [
    {
      "key": "metadata3",
      "value": "A new value"
    }
  ]
}

Figure 2: Example of adding new metadata to an ApplicationInstance element

The result will be that the element has 3 metadata elements: metadata1, metadata2 and metadata3.

When you want to update metadata, you only have to submit that one metadata element:

PUT /applicationInstance/{applicationInstanceId}

{
  "metadata": [
    {
      "key": "metadata2",
      "value": "An updated value"
    }
  ]
}

Figure 3: Example of updating an existing metadata element in an ApplicationInstance element

Deleting metadata is done by submitting metadata with a null value:

PUT /applicationInstance/{applicationInstanceId}

{
  "metadata": [
    {
      "key": "metadata2",
      "value": null
    }
  ]
}

Figure 4: Example of deleting metadata from an ApplicationInstance element

After these example mutations, the element ends up with the following metadata:

GET /applicationInstance/{applicationInstanceId}

{
  "metadata": [
    {
      "key": "metadata1",
      "value": "A value"
    },
    {
      "key": "metadata3",
      "value": "A new value"
    }
  ]
}

Figure 5: The resulting metadata for an ApplicationInstance element after applying the examples

Adding metadata during ApplicationInstance allocation

During an allocation call (API reference), you can pass a metadata array. This metadata will then be added to all the ApplicationInstances that are allocated during that request.

PUT /applicationInstance/game/{applicationId}/empty/allocate

{
  "metadata": [
    {
      "key": "metadata1",
      "value": "E.g. a map name"
    },
    {
      "key": "metadata2",
      "value": "E.g. game duration"
    }
  ]
}

Figure 6: Example of passing metadata to ApplicationInstances being allocated

Metadata sent during an allocation request will be merged with the metadata of the ApplicationInstances that are allocated. Merging occurs in the same manner as manually updating metadata.