> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

创建指定的匹配票证。

> **重要:**\
> 此方法拟用于合约 103 或更高版本,并且要求每次请求都包含 X-Xbl-Contract-Version: 103 或更高版本的标头元素。

* [备注](#ID4ET)
* [URI 参数](#ID4E5)
* [授权](#ID4EJB)
* [HTTP 状态代码](#ID4E3C)
* [请求正文](#ID4EFD)
* [响应正文](#ID4E3G)

## 备注

此 HTTP/REST 方法会在服务配置 ID (SCID) 层级为具有特定名称的 hopper 创建一个匹配票证。此方法可以由 **Microsoft.Xbox.Services.Matchmaking.MatchmakingService.CreateMatchTicketAsync** 方法进行包装。

## URI 参数

| 参数 | 类型 | 说明 |
| - | - | - |
| scid | GUID | 会话的服务配置标识符 (SCID)。 |
| hoppername | string | hopper 的名称。 |

## 授权

| 类型 | 是否必需 | 说明 | 缺失时的响应 |
| - | - | - | - |
| 权限和设备类型 | 是 | 当用户的 deviceType 设置为 console 时,只有其声明中包含 multiplayer 权限的用户才能调用匹配服务。 | 403 |
| 设备类型 | 是 | 当用户的 deviceType 缺失或设置为非 console 时,要匹配的游戏不得为仅限主机的游戏。 | 403 |
| 游戏 ID/购买证明/设备类型 | 是 | 要匹配的游戏必须允许针对指定的标题声明、设备类型组合进行匹配。 | 403 |

## HTTP 状态代码

服务返回适用于 MPSD 的 HTTP 状态代码。

## 请求正文

### 必需成员

| 成员 | 类型 | 说明 |
| - | - | - |
| serviceConfig | GUID | 会话的 SCID。 |
| hopperName | string | hopper 的名称。 |
| giveUpDuration | 32 位有符号整数 | 最长等待时间(整数秒数)。 |
| preserveSession | 枚举 | 一个值,指示是否将会话重用为要匹配到的会话。可能的值为 "always" 和 "never"。 |
| ticketSessionRef | MultiplayerSessionReference | 玩家或组当前所在游戏会话的 MultiplayerSessionReference 对象。 |
| ticketAttributes | 对象集合 | 用户提供的关于玩家组的属性和值。 |

### 禁止的成员

请求中禁止使用所有其他成员。

### 请求示例

在创建匹配票证之前,必须先创建 **ticketSessionRef** 对象所引用的会话,并且该会话必须包含要匹配的玩家及其特定于玩家的属性。每个玩家都必须针对 MPSD 创建或加入该会话,并将相关的匹配属性添加到会话中。这些匹配属性放置在每个玩家上一个名为 matchAttrs 的自定义属性字段中。

创建或加入请求提交到 **[https://sessiondirectory.xboxlive.com/serviceconfigs/\{scid}/sessiontemplates/\{templatename}/sessions/\{sessionname}](https://sessiondirectory.xboxlive.com/serviceconfigs/\{scid}/sessiontemplates/\{templatename}/sessions/\{sessionname})**,可能如下所示:

```cpp theme={null}
{
   "members": {
     "me": {
       "constants": {
         "system": {
           "xuid": 2535285330879750
         }
      },
      "properties": {
         "custom": {
           "matchAttrs": {
             "skill": 5,
             "ageRange": "teenager"
           }
         }
      }
    }
  }
}

```

创建会话后,游戏可以调用匹配服务为该会话创建票证。

> **注意:**
> 游戏可以允许用户重试此调用,但如果数据失败,则不应自动重试。

```cpp theme={null}
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"
  }
}

```

## 响应正文

| 成员 | 类型 | 说明 |
| - | - | - |
| ticketId | GUID | 所创建票证的 ID。 |
| waitTime | 32 位有符号整数 | hopper 的平均等待时间(整数秒数)。 |

```cpp theme={null}
{
  "ticketId":"0584338f-a2ff-4eb9-b167-c0e8ddecae72",
  "waitTime":60
}

```

## 另请参阅

## 父主题

[/serviceconfigs/{scid}/hoppers/{hoppername}](https://devdocs.xbox.com/zh-CN/reference/live/rest/uri/matchtickets/uri-serviceconfigsscidhoppershoppername)


## Related topics

- [Multiplayer tasks](https://devdocs.xbox.com/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-how-tos.md)
- [Tarefas de multijogador](https://devdocs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-how-tos.md)
- [Tareas multijugador](https://devdocs.xbox.com/es/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-how-tos.md)
- [Tâches multijoueurs](https://devdocs.xbox.com/fr-CA/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-how-tos.md)
- [XblMatchmakingGetHopperStatisticsAsync](https://devdocs.xbox.com/reference/live/xsapi-c/matchmaking_c/functions/xblmatchmakinggethopperstatisticsasync.md)