Skip to content
AWS for Query.Farm

aws.gamelift.describe_matchmaking

Example SQL Queries

SELECT * FROM
aws.gamelift.describe_matchmaking
WHERE
"ticket_ids" = 'VALUE';

Description

Retrieves one or more matchmaking tickets. Use this operation to retrieve ticket information, including--after a successful match is made--connection information for the resulting new game session.

To request matchmaking tickets, provide a list of up to 10 ticket IDs. If the request is successful, a ticket object is returned for each requested ID that currently exists.

This operation is not designed to be continually called to track matchmaking ticket status. This practice can cause you to exceed your API limit, which results in errors. Instead, as a best practice, set up an Amazon Simple Notification Service to receive notifications, and provide the topic ARN in the matchmaking configuration.

Learn more

Add FlexMatch to a game client

Set Up FlexMatch event notification

Table Definition

Column NameColumn Data Type
ticket_ids Required Input Column

A unique identifier for a matchmaking ticket. You can include up to 10 ID values. 

VARCHAR[]
Show child fields
ticket_ids[]
_aws_profile Input Column

The AWS profile defines the AWS identity used. It can be defined via credentials or by assuming a IAM role.

STRUCT(
    "type" VARCHAR,
    "name" VARCHAR,
    "account_id" VARCHAR,
    "via_profile_name" VARCHAR,
    "assumed_role_arn" VARCHAR,
    "organization" STRUCT(
        "account_name" VARCHAR,
        "id" VARCHAR,
        "tags" STRUCT(
            "key" VARCHAR,
            "value" VARCHAR
        )[],
        "master_account" STRUCT(
            "id" VARCHAR,
            "email" VARCHAR
        ),
        "parents" STRUCT(
            "type" VARCHAR,
            "id" VARCHAR,
            "name" VARCHAR,
            "tags" STRUCT(
                "key" VARCHAR,
                "value" VARCHAR
            )[]
        )[]
    )
)
Show child fields
_aws_profile.account_id

The AWS account id

_aws_profile.assumed_role_arn

The ARN of the assumed role

_aws_profile.name

The unique name of the profile.

_aws_profile.organization

Information about this profile's membership in the AWS organization.

Show child fields
_aws_profile.organization.account_name

The name of account speciifed by the organization

_aws_profile.organization.id

The organization id

_aws_profile.organization.master_account
Show child fields
_aws_profile.organization.master_account.email

The organization master account email address

_aws_profile.organization.master_account.id

The organization master account id

_aws_profile.organization.parents[]
Show child fields
_aws_profile.organization.parents[].id

The id of the parent

_aws_profile.organization.parents[].name

The name of the parent

_aws_profile.organization.parents[].tags[]
Show child fields
_aws_profile.organization.parents[].tags[].key
_aws_profile.organization.parents[].tags[].value
_aws_profile.organization.parents[].type

The type of parent can be an organization unit or a root

_aws_profile.organization.tags[]
Show child fields
_aws_profile.organization.tags[].key
_aws_profile.organization.tags[].value
_aws_profile.type

The type of profile, either 'credentials' or 'assumed_role'

_aws_profile.via_profile_name

This IAM role for this profile is assumed by first utilizing another profile with this name to obtain credentials.

_aws_region Input Column

The AWS region to use.

VARCHAR
ticket_list

A collection of existing matchmaking ticket objects matching the request.

STRUCT(
    "ticket_id" VARCHAR,
    "configuration_name" VARCHAR,
    "configuration_arn" VARCHAR,
    "status" VARCHAR,
    "status_reason" VARCHAR,
    "status_message" VARCHAR,
    "start_time" TIMESTAMP_S,
    "end_time" TIMESTAMP_S,
    "players" STRUCT(
        "player_id" VARCHAR,
        "player_attributes" MAP(VARCHAR, STRUCT(
                "s" VARCHAR,
                "n" DOUBLE,
                "sl" VARCHAR[],
                "sdm" MAP(VARCHAR, DOUBLE)
            )),
        "team" VARCHAR,
        "latency_in_ms" MAP(VARCHAR, BIGINT)
    )[],
    "game_session_connection_info" STRUCT(
        "game_session_arn" VARCHAR,
        "ip_address" VARCHAR,
        "dns_name" VARCHAR,
        "port" BIGINT,
        "matched_player_sessions" STRUCT(
            "player_id" VARCHAR,
            "player_session_id" VARCHAR
        )[]
    ),
    "estimated_wait_time" BIGINT
)[]
Show child fields
ticket_list[]
Show child fields
ticket_list[].configuration_arn

The Amazon Resource Name (ARN) associated with the GameLift matchmaking configuration resource that is used with this ticket.

ticket_list[].configuration_name

Name of the matchmaking configuration that is used with this ticket. Matchmaking configurations determine how players are grouped into a match and how a new game session is created for the match.

ticket_list[].end_time

Time stamp indicating when the matchmaking request stopped being processed due to successful completion, timeout, or cancellation. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").

ticket_list[].estimated_wait_time

Average amount of time (in seconds) that players are currently waiting for a match. If there is not enough recent data, this property may be empty.

ticket_list[].game_session_connection_info

Connection information for a new game session. Once a match is made, the FlexMatch engine creates a new game session for it. This information is added to the matchmaking ticket, which you can be retrieve by calling DescribeMatchmaking .

Show child fields
ticket_list[].game_session_connection_info.dns_name

The DNS identifier assigned to the instance that is running the game session. Values have the following format:

  • TLS-enabled fleets: <unique identifier>.<region identifier>.amazongamelift.com.

  • Non-TLS-enabled fleets: ec2-<unique identifier>.compute.amazonaws.com. (See Amazon EC2 Instance IP Addressing.)

When connecting to a game session that is running on a TLS-enabled fleet, you must use the DNS name, not the IP address.

ticket_list[].game_session_connection_info.game_session_arn

A unique identifier for the game session. Use the game session ID.

ticket_list[].game_session_connection_info.ip_address

The IP address of the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.

ticket_list[].game_session_connection_info.matched_player_sessions[]
Show child fields
ticket_list[].game_session_connection_info.matched_player_sessions[].player_id

A unique identifier for a player

ticket_list[].game_session_connection_info.matched_player_sessions[].player_session_id

A unique identifier for a player session

ticket_list[].game_session_connection_info.port

The port number for the game session. To connect to a Amazon GameLift game server, an app needs both the IP address and port number.

ticket_list[].players[]
Show child fields
ticket_list[].players[].latency_in_ms

A set of values, expressed in milliseconds, that indicates the amount of latency that a player experiences when connected to @aws; Regions. If this property is present, FlexMatch considers placing the match only in Regions for which latency is reported.

If a matchmaker has a rule that evaluates player latency, players must report latency in order to be matched. If no latency is reported in this scenario, FlexMatch assumes that no Regions are available to the player and the ticket is not matchable.

ticket_list[].players[].player_attributes

A collection of key:value pairs containing player information for use in matchmaking. Player attribute keys must match the playerAttributes used in a matchmaking rule set. Example: "PlayerAttributes": {"skill": {"N": "23"}, "gameMode": {"S": "deathmatch"}}.

You can provide up to 10 PlayerAttributes.

ticket_list[].players[].player_id

A unique identifier for a player

ticket_list[].players[].team

Name of the team that the player is assigned to in a match. Team names are defined in a matchmaking rule set.

ticket_list[].start_time

Time stamp indicating when this matchmaking request was received. Format is a number expressed in Unix time as milliseconds (for example "1469498468.057").

ticket_list[].status

Current status of the matchmaking request.

  • QUEUED -- The matchmaking request has been received and is currently waiting to be processed.

  • SEARCHING -- The matchmaking request is currently being processed.

  • REQUIRES_ACCEPTANCE -- A match has been proposed and the players must accept the match. This status is used only with requests that use a matchmaking configuration with a player acceptance requirement.

  • PLACING -- The FlexMatch engine has matched players and is in the process of placing a new game session for the match.

  • COMPLETED -- Players have been matched and a game session is ready to host the players. A ticket in this state contains the necessary connection information for players.

  • FAILED -- The matchmaking request was not completed.

  • CANCELLED -- The matchmaking request was canceled. This may be the result of a StopMatchmaking operation or a proposed match that one or more players failed to accept.

  • TIMED_OUT -- The matchmaking request was not successful within the duration specified in the matchmaking configuration.

Matchmaking requests that fail to successfully complete (statuses FAILED, CANCELLED, TIMED_OUT) can be resubmitted as new requests with new ticket IDs.

ticket_list[].status_message

Additional information about the current status.

ticket_list[].status_reason

Code to explain the current status. For example, a status reason may indicate when a ticket has returned to SEARCHING status after a proposed match fails to receive player acceptances.

ticket_list[].ticket_id

A unique identifier for a matchmaking ticket.