> ## 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.

# PFMultiplayerCreateMatchmakingTicket

> 為一或多個本機使用者建立 PlayFab Multiplayer 配對票證，將他們提交至指定的佇列以與其他玩家配對。

為一或多個本機使用者建立配對票證。

## 語法

```cpp theme={null}
HRESULT PFMultiplayerCreateMatchmakingTicket(  
    PFMultiplayerHandle handle,  
    uint32_t localUserCount,  
    const PFEntityKey* localUsers,  
    const char* const* localUserAttributes,  
    const PFMatchmakingTicketConfiguration* configuration,  
    void* asyncContext,  
    PFMatchmakingTicketHandle* ticket  
)  
```

### 參數

**`handle`**   PFMultiplayerHandle

PFMultiplayer API 執行個體的控制代碼。

**`localUserCount`**   uint32\_t

要包含在票證中的本機使用者計數。

**`localUsers`**   [PFEntityKey\*](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/pfentitykey_clientsdk)\
*大小為 `localUserCount` 的輸入陣列*

要包含在票證中的本機使用者陣列。

**`localUserAttributes`**   char\* const\*\
*大小為 `localUserCount` 的輸入陣列*

本機使用者屬性字串的陣列。每個本機使用者應有一個屬性字串。每個屬性字串應為空字串或序列化的 JSON 物件。例如：`{"player_color":"blue","player_role":"tank"}`。

**`configuration`**   [PFMatchmakingTicketConfiguration\*](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketconfiguration)

票證設定。

**`asyncContext`**   void\*\
*選用*

選用的應用程式定義指標大小內容值，可用來將完成狀態變更與此呼叫建立關聯。

**`ticket`**   PFMatchmakingTicketHandle\*\
*程式庫配置的輸出*

產生的票證物件。

### 傳回值

類型：HRESULT

如果呼叫成功，則為 `S_OK`；否則為錯誤碼。可透過 [PFMultiplayerGetErrorMessage()](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayergeterrormessage) 擷取錯誤碼的人類可讀形式。

## 備註

程式庫會自動以非同步方式將票證上所有指定的本機使用者提交至配對服務。每次票證狀態變更時，都會提供 [PFMatchmakingTicketStatusChangedStateChange](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketstatuschangedstatechange)。可隨時透過 [PFMatchmakingTicketGetStatus()](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetstatus) 查詢票證狀態。票證會立即以 `PFMatchmakingTicketStatus::Creating` 狀態開始。 <br /><br /> 票證完成時，會提供 [PFMatchmakingTicketStatusChangedStateChange](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketstatuschangedstatechange)。此時，已找到比賽或票證因失敗而停止。成功時，可透過 [PFMatchmakingTicketGetMatch()](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetmatch) 查詢找到的比賽。   <br /><br /> 如果票證建立因指定使用者已有太多票證而失敗，程式庫會以透明方式取消那些未完成的票證，然後重試建立票證。   <br /><br /> 在 `configuration` 參數之 `membersToMatchWith` 欄位中指定的所有遠端使用者透過 [PFMultiplayerJoinMatchmakingTicketFromId()](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerjoinmatchmakingticketfromid) 加入票證之前，無法找到比賽。

## 需求

**標頭：** PFMatchmaking.h

## 另請參閱

[PFMatchmaking 成員](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/pfmatchmaking_members)


## Related topics

- [從 MPSD 移至 PlayFab Multiplayer 與 MPA](/zh-TW/services/xbox-services/multiplayer/mpsd/concepts/live-mpsd-to-mlp.md)
- [Matchmaking SDK 快速入門](/zh-TW/services/playfab/multiplayer/matchmaking/quickstart-client-sdk.md)
- [PFMultiplayer C/C++ API 概觀 - PFMatchmaking.h](/zh-TW/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/pfmatchmaking_members.md)
- [非同步 Lobby 和 Matchmaking C++ SDK 作業指南](/zh-TW/services/playfab/multiplayer/lobby/lobby-and-matchmaking-client-sdk-async.md)
- [Create Matchmaking Ticket](/api-reference/matchmaking/create-matchmaking-ticket.md)