Compartir a través de

POST (/serviceconfigs/{scid}/hoppers/{hoppername})

  • Artículo

Creates the specified match ticket.

Important:
This method is intended for use with contract 103 or later, and requires a header element of X-Xbl-Contract-Version: 103 or later on every request.

Remarks

This HTTP/REST method creates a match ticket for a hopper with a particular name at the service configuration ID (SCID) level. This method can be wrapped by the Microsoft.Xbox.Services.Matchmaking.MatchmakingService.CreateMatchTicketAsync method.

URI parameters

Parameter Type Description
scid GUID The service configuration identifier (SCID) for the session.
hoppername string The name of the hopper.

Authorization

Type Required Description Response if missing
Privileges and Device Type yes When the user's deviceType is set to console, only users with the multiplayer privilege in their claims are allowed to make calls to the matchmaking service. 403
Device Type yes When the user's deviceType is absent or set to non-console, the title being matched into must not be a console-only title. 403
Title ID/Proof of Purchase/Device Type yes The title that is being matched into must allow matchmaking for the specified title claim, device type combination. 403

HTTP status codes

The service returns an HTTP status code as it applies to MPSD.

Request body

Required members

Member Type Description
serviceConfig GUID SCID for the session.
hopperName string Name of the hopper.
giveUpDuration 32-bit signed integer Maximum wait time (integral number of seconds).
preserveSession enumeration A value indicating if the session is reused as the session into which to match. Possible values are "always" and "never".
ticketSessionRef MultiplayerSessionReference The MultiplayerSessionReference object for the session in which the player or group is currently playing.
ticketAttributes collection of objects Attributes and values provided by the user about the group of players.

Prohibited members

All other members are prohibited in a request.

Sample request

The session referred to by the ticketSessionRef object must be created before a match ticket can be created, and the session must contain the players to be matched, along with their player-specific attributes. Each player must create or join the session against the MPSD, adding associated match attributes to the session. The match attributes are placed in a custom property field called matchAttrs on each player.

A create or join request is submitted to https://sessiondirectory.xboxlive.com/serviceconfigs/{scid}/sessiontemplates/{templatename}/sessions/{sessionname} and might look like this:

{
   "members": {
     "me": {
       "constants": {
         "system": {
           "xuid": 2535285330879750
         }
      },
      "properties": {
         "custom": {
           "matchAttrs": {
             "skill": 5,
             "ageRange": "teenager"
           }
         }
      }
    }
  }
}

Once the session has been created, the title can call the matchmaking service to create the ticket for that session.

Note: A title can enable a user to retry this call, but should not retry it automatically if the data fails.

POST /serviceconfigs/{scid}/hoppers/{hoppername}

{
  "giveUpDuration":10,
  "preserveSession": "never",
  "ticketSessionRef": {
     "scid": "ABBACDDC-0000-0000-0000-000000000001",  
     "templateName": "TestTemplate",
     "name": "5E55104-0000-0000-0000-000000000001"
  },
  "ticketAttributes": {
    "desiredMap": "Test Map",
    "desiredGameType": "Test GameType"
  }
}

Response body

Member Type Description
ticketId GUID The ID for the ticket being created.
waitTime 32-bit signed integer The average wait time for the hopper (integral number of seconds). 
{
  "ticketId":"0584338f-a2ff-4eb9-b167-c0e8ddecae72",
  "waitTime":60
}

See also

Parent

/serviceconfigs/{scid}/hoppers/{hoppername}