feat(client-gamelift): Amazon GameLift adds the ability to add and up…

…date the game properties of active game sessions.
aws · Dec 14, 2023 · 9c8b6c6 · 9c8b6c6
1 parent f6658b4
commit 9c8b6c6
Show file tree

Hide file tree

Showing 5 changed files with 84 additions and 49 deletions.
diff --git a/clients/client-gamelift/src/commands/SearchGameSessionsCommand.ts b/clients/client-gamelift/src/commands/SearchGameSessionsCommand.ts
@@ -43,12 +43,7 @@ export interface SearchGameSessionsCommandOutput extends SearchGameSessionsOutpu
  * @public
  * <p>Retrieves all active game sessions that match a set of search criteria and sorts them
  *             into a specified order. </p>
- *          <p>This operation is not designed to be continually called to track game session status.
- *             This practice can cause you to exceed your API limit, which results in errors. Instead,
- *             you must configure configure an Amazon Simple Notification Service (SNS) topic to receive notifications from
- *             FlexMatch or queues. Continuously polling game session status with
- *                 <code>DescribeGameSessions</code> should only be used for games in development with
- *             low game session usage. </p>
+ *          <p>This operation is not designed to continually track game session status because that practice can cause you to exceed your API limit and generate errors. Instead, configure an Amazon Simple Notification Service (Amazon SNS) topic to receive notifications from a matchmaker or game session placement queue.</p>
  *          <p>When searching for game sessions, you specify exactly where you want to search and
  *             provide a search filter expression, a sort expression, or both. A search request can
  *             search only one fleet, but it can search all of a fleet's locations. </p>
@@ -70,7 +65,7 @@ export interface SearchGameSessionsCommandOutput extends SearchGameSessionsOutpu
  *          <p>If successful, a <code>GameSession</code> object is returned for each game session
  *             that matches the request. Search finds game sessions that are in <code>ACTIVE</code>
  *             status only. To retrieve information on game sessions in other statuses, use <a href="https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeGameSessions.html">DescribeGameSessions</a> .</p>
- *          <p>You can search or sort by the following game session attributes:</p>
+ *          <p>To set search and sort criteria, create a filter expression using the following game session attributes. For game session search examples, see the Examples section of this topic.</p>
  *          <ul>
  *             <li>
  *                <p>
@@ -84,14 +79,14 @@ export interface SearchGameSessionsCommandOutput extends SearchGameSessionsOutpu
  *             </li>
  *             <li>
  *                <p>
- *                   <b>gameSessionProperties</b> -- Custom data defined
- *                     in a game session's <code>GameProperty</code> parameter.
- *                         <code>GameProperty</code> values are stored as key:value pairs; the filter
- *                     expression must indicate the key and a string to search the data values for. For
- *                     example, to search for game sessions with custom data containing the key:value
- *                     pair "gameMode:brawl", specify the following:
- *                         <code>gameSessionProperties.gameMode = "brawl"</code>. All custom data
- *                     values are searched as strings.</p>
+ *                   <b>gameSessionProperties</b> -- A set of key-value pairs that can store custom data in a game session.
+ *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>.
+ *                     The filter expression must specify the <a>GameProperty</a> -- a <code>Key</code> and a string <code>Value</code> to search for the game sessions.</p>
+ *                <p>For example, to search for the above key-value pair, specify the following search filter: <code>gameSessionProperties.difficulty = "novice"</code>.
+ *                     All game property values are searched as strings.</p>
+ *                <p>
+ *                     For examples of searching game sessions, see the ones below, and also see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-client-api.html#game-properties-search">Search game sessions by game property</a>.
+ *                     </p>
  *             </li>
  *             <li>
  *                <p>

diff --git a/clients/client-gamelift/src/commands/UpdateGameSessionCommand.ts b/clients/client-gamelift/src/commands/UpdateGameSessionCommand.ts
@@ -60,6 +60,12 @@ export interface UpdateGameSessionCommandOutput extends UpdateGameSessionOutput,
  *   Name: "STRING_VALUE",
  *   PlayerSessionCreationPolicy: "ACCEPT_ALL" || "DENY_ALL",
  *   ProtectionPolicy: "NoProtection" || "FullProtection",
+ *   GameProperties: [ // GamePropertyList
+ *     { // GameProperty
+ *       Key: "STRING_VALUE", // required
+ *       Value: "STRING_VALUE", // required
+ *     },
+ *   ],
  * };
  * const command = new UpdateGameSessionCommand(input);
  * const response = await client.send(command);

diff --git a/clients/client-gamelift/src/models/models_0.ts b/clients/client-gamelift/src/models/models_0.ts
@@ -2877,11 +2877,15 @@ export interface CreateGameServerGroupOutput {
 
 /**
  * @public
- * <p>Set of key-value pairs that contain information about a game session. When included in
- *             a game session request, these properties communicate details to be used when setting up
- *             the new game session. For example, a game property might specify a game mode, level, or
- *             map. Game properties are passed to the game server process when initiating a new game
- *             session. For more information, see the <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-client-api.html#gamelift-sdk-client-api-create"> Amazon GameLift Developer Guide</a>.</p>
+ * <p>This key-value pair can store custom data about a game session.
+ *         For example, you might use a <code>GameProperty</code> to track a game session's map, level of difficulty, or remaining time.
+ *         The difficulty level could be specified like this: <code>\{"Key": "difficulty", "Value":"Novice"\}</code>.
+ *       </p>
+ *          <p>
+ *           You can set game properties when creating a game session. You can also modify game properties of an active game session. When searching for game sessions, you can filter on game property keys and values. You can't delete game properties from a game session.
+ *       </p>
+ *          <p>For examples of working with game properties, see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-client-api.html#game-properties">Create a game session with properties</a>.
+ *       </p>
  */
 export interface GameProperty {
   /**
@@ -2930,7 +2934,10 @@ export interface CreateGameSessionInput {
 
   /**
    * @public
-   * <p>A set of custom properties for a game session, formatted as key:value pairs. These properties are passed to a game server process with a request to start a new game session (see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-server-api.html#gamelift-sdk-server-startsession">Start a Game Session</a>).</p>
+   * <p>A set of key-value pairs that can store custom data in a game session.
+   *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>.
+   *           For an example, see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-client-api.html#game-properties-create">Create a game session with custom properties</a>.
+   *         </p>
    */
   GameProperties?: GameProperty[];
 
@@ -3116,7 +3123,8 @@ export interface GameSession {
 
   /**
    * @public
-   * <p>A set of custom properties for a game session, formatted as key:value pairs. These properties are passed to a game server process with a request to start a new game session (see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-server-api.html#gamelift-sdk-server-startsession">Start a Game Session</a>).</p>
+   * <p>A set of key-value pairs that can store custom data in a game session.
+   *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>.</p>
    */
   GameProperties?: GameProperty[];
 
@@ -3715,7 +3723,8 @@ export interface CreateMatchmakingConfigurationInput {
 
   /**
    * @public
-   * <p>A set of custom properties for a game session, formatted as key:value pairs. These properties are passed to a game server process with a request to start a new game session (see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-server-api.html#gamelift-sdk-server-startsession">Start a Game Session</a>). This information is added to the new <code>GameSession</code> object that is
+   * <p>A set of key-value pairs that can store custom data in a game session.
+   *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>. This information is added to the new <code>GameSession</code> object that is
    *             created for a successful match. This parameter is not used if <code>FlexMatchMode</code>
    *             is set to <code>STANDALONE</code>.</p>
    */
@@ -3872,7 +3881,8 @@ export interface MatchmakingConfiguration {
 
   /**
    * @public
-   * <p>A set of custom properties for a game session, formatted as key:value pairs. These properties are passed to a game server process with a request to start a new game session (see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-server-api.html#gamelift-sdk-server-startsession">Start a Game Session</a>). This information is added to the new <code>GameSession</code> object that is
+   * <p>A set of key-value pairs that can store custom data in a game session.
+   *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>. This information is added to the new <code>GameSession</code> object that is
    *             created for a successful match. This parameter is not used when
    *                 <code>FlexMatchMode</code> is set to <code>STANDALONE</code>.</p>
    */
@@ -5466,18 +5476,19 @@ export interface Event {
    *             </li>
    *             <li>
    *                <p>SERVER_PROCESS_SDK_INITIALIZATION_TIMEOUT -- The server process did not call
-   *                     InitSDK() within the time expected. Check your game session log to see why
-   *                     InitSDK() was not called in time.</p>
+   *                         <code>InitSDK()</code> within the time expected (5 minutes). Check your game
+   *                     session log to see why <code>InitSDK()</code> was not called in time.</p>
    *             </li>
    *             <li>
    *                <p>SERVER_PROCESS_PROCESS_READY_TIMEOUT -- The server process did not call
-   *                     ProcessReady() within the time expected after calling InitSDK(). Check your game
-   *                     session log to see why ProcessReady() was not called in time.</p>
+   *                         <code>ProcessReady()</code> within the time expected  (5 minutes) after
+   *                     calling <code>InitSDK()</code>. Check your game session log to see why
+   *                         <code>ProcessReady()</code> was not called in time.</p>
    *             </li>
    *             <li>
    *                <p>SERVER_PROCESS_CRASHED -- The server process exited without calling
-   *                     ProcessEnding(). Check your game session log to see why ProcessEnding() was not
-   *                     called.</p>
+   *                         <code>ProcessEnding()</code>. Check your game session log to see why
+   *                         <code>ProcessEnding()</code> was not called.</p>
    *             </li>
    *             <li>
    *                <p>SERVER_PROCESS_TERMINATED_UNHEALTHY -- The server process did not report a
@@ -5487,13 +5498,14 @@ export interface Event {
    *             </li>
    *             <li>
    *                <p>SERVER_PROCESS_FORCE_TERMINATED -- The server process did not exit cleanly
-   *                     after OnProcessTerminate() was sent within the time expected. Check your game
-   *                     session log to see why termination took longer than expected.</p>
+   *                     within the time expected after <code>OnProcessTerminate()</code> was sent. Check
+   *                     your game session log to see why termination took longer than expected.</p>
    *             </li>
    *             <li>
    *                <p>SERVER_PROCESS_PROCESS_EXIT_TIMEOUT -- The server process did not exit cleanly
-   *                     within the time expected after calling ProcessEnding(). Check your game session
-   *                     log to see why termination took longer than expected.</p>
+   *                     within the time expected (30 seconds) after calling
+   *                     <code>ProcessEnding()</code>. Check your game session log to see why termination
+   *                     took longer than expected.</p>
    *             </li>
    *          </ul>
    *          <p>
@@ -5502,8 +5514,9 @@ export interface Event {
    *          <ul>
    *             <li>
    *                <p>GAME_SESSION_ACTIVATION_TIMEOUT -- GameSession failed to activate within the
-   *                     expected time. Check your game session log to see why ActivateGameSession() took
-   *                     longer to complete than expected.</p>
+   *                     expected time. Check your game session log to see why
+   *                         <code>ActivateGameSession()</code> took longer to complete than
+   *                     expected.</p>
    *             </li>
    *          </ul>
    *          <p>
@@ -6289,7 +6302,8 @@ export interface GameSessionPlacement {
 
   /**
    * @public
-   * <p>A set of custom properties for a game session, formatted as key:value pairs. These properties are passed to a game server process with a request to start a new game session (see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-server-api.html#gamelift-sdk-server-startsession">Start a Game Session</a>).</p>
+   * <p>A set of key-value pairs that can store custom data in a game session.
+   *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>.</p>
    */
   GameProperties?: GameProperty[];
 
@@ -9010,7 +9024,8 @@ export interface StartGameSessionPlacementInput {
 
   /**
    * @public
-   * <p>A set of custom properties for a game session, formatted as key:value pairs. These properties are passed to a game server process with a request to start a new game session (see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-server-api.html#gamelift-sdk-server-startsession">Start a Game Session</a>).</p>
+   * <p>A set of key-value pairs that can store custom data in a game session.
+   *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>.</p>
    */
   GameProperties?: GameProperty[];
 

diff --git a/clients/client-gamelift/src/models/models_1.ts b/clients/client-gamelift/src/models/models_1.ts
@@ -329,6 +329,18 @@ export interface UpdateGameSessionInput {
    *          </ul>
    */
   ProtectionPolicy?: ProtectionPolicy;
+
+  /**
+   * @public
+   * <p>A set of key-value pairs that can store custom data in a game session.
+   *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>.
+   *         You can use this parameter to modify game properties in an active game session.
+   *         This action adds new properties and modifies existing properties.
+   *         There is no way to delete properties.
+   *         For an example, see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-client-api.html#game-properties-update">Update the value of a game property</a>.
+   *       </p>
+   */
+  GameProperties?: GameProperty[];
 }
 
 /**
@@ -498,7 +510,8 @@ export interface UpdateMatchmakingConfigurationInput {
 
   /**
    * @public
-   * <p>A set of custom properties for a game session, formatted as key:value pairs. These properties are passed to a game server process with a request to start a new game session (see <a href="https://docs.aws.amazon.com/gamelift/latest/developerguide/gamelift-sdk-server-api.html#gamelift-sdk-server-startsession">Start a Game Session</a>). This information is added to the new <code>GameSession</code> object that is
+   * <p>A set of key-value pairs that can store custom data in a game session.
+   *   For example: <code>\{"Key": "difficulty", "Value": "novice"\}</code>. This information is added to the new <code>GameSession</code> object that is
    *             created for a successful match. This parameter is not used if <code>FlexMatchMode</code>
    *             is set to <code>STANDALONE</code>.</p>
    */