將角色授與使用者

Grants the specified character type to the user. CharacterIds are not globally unique; characterId must be evaluated with the parent PlayFabId to guarantee uniqueness.

Error codes

This operation may return the following PlayFab errors:

Error	Code
InvalidItemProperties	1091
ItemNotOwned	1048

POST

Client

GrantCharacterToUser

Grant Character To User

curl --request POST \
  --url https://{titleId}.playfabapi.com/Client/GrantCharacterToUser \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '
{
  "CatalogVersion": "2.2",
  "ItemId": "Blue Warrior",
  "CharacterName": "FighterDude"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Client/GrantCharacterToUser"

payload = {
    "CatalogVersion": "2.2",
    "ItemId": "Blue Warrior",
    "CharacterName": "FighterDude"
}
headers = {
    "X-Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Authorization': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({CatalogVersion: '2.2', ItemId: 'Blue Warrior', CharacterName: 'FighterDude'})
};

fetch('https://{titleId}.playfabapi.com/Client/GrantCharacterToUser', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Client/GrantCharacterToUser",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'CatalogVersion' => '2.2',
    'ItemId' => 'Blue Warrior',
    'CharacterName' => 'FighterDude'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Client/GrantCharacterToUser"

	payload := strings.NewReader("{\n  \"CatalogVersion\": \"2.2\",\n  \"ItemId\": \"Blue Warrior\",\n  \"CharacterName\": \"FighterDude\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Client/GrantCharacterToUser")
  .header("X-Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"CatalogVersion\": \"2.2\",\n  \"ItemId\": \"Blue Warrior\",\n  \"CharacterName\": \"FighterDude\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Client/GrantCharacterToUser")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"CatalogVersion\": \"2.2\",\n  \"ItemId\": \"Blue Warrior\",\n  \"CharacterName\": \"FighterDude\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "CharacterId": "98765432",
    "CharacterType": "Blue Warrior",
    "Result": true
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

授權

X-Authorization

string

header

必填

This API requires a client session ticket, available from any Client Login function.

主體

application/json

Grants a character to the user of the type specified by the item ID. The user must already have an instance of this item in their inventory in order to allow character creation. This item can come from a purchase or grant, which must be done before calling to create the character.

CharacterName

string

必填

Non-unique display name of the character being granted (1-40 characters in length).

ItemId

string

必填

Catalog item identifier of the item in the user's inventory that corresponds to the character in the catalog to be created.

CatalogVersion

string

Catalog version from which items are to be granted.

CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).

回應

code

integer

The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code.

status

string

The Http status code as a string.

data

object

Show child attributes

範例:

{
  "CharacterId": "98765432",
  "CharacterType": "Blue Warrior",
  "Result": true
}

最後修改於 2026年10月6日

⌘I

Grant Character To User

curl --request POST \
  --url https://{titleId}.playfabapi.com/Client/GrantCharacterToUser \
  --header 'Content-Type: application/json' \
  --header 'X-Authorization: <api-key>' \
  --data '
{
  "CatalogVersion": "2.2",
  "ItemId": "Blue Warrior",
  "CharacterName": "FighterDude"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Client/GrantCharacterToUser"

payload = {
    "CatalogVersion": "2.2",
    "ItemId": "Blue Warrior",
    "CharacterName": "FighterDude"
}
headers = {
    "X-Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Authorization': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({CatalogVersion: '2.2', ItemId: 'Blue Warrior', CharacterName: 'FighterDude'})
};

fetch('https://{titleId}.playfabapi.com/Client/GrantCharacterToUser', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Client/GrantCharacterToUser",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'CatalogVersion' => '2.2',
    'ItemId' => 'Blue Warrior',
    'CharacterName' => 'FighterDude'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Client/GrantCharacterToUser"

	payload := strings.NewReader("{\n  \"CatalogVersion\": \"2.2\",\n  \"ItemId\": \"Blue Warrior\",\n  \"CharacterName\": \"FighterDude\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Client/GrantCharacterToUser")
  .header("X-Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"CatalogVersion\": \"2.2\",\n  \"ItemId\": \"Blue Warrior\",\n  \"CharacterName\": \"FighterDude\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Client/GrantCharacterToUser")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"CatalogVersion\": \"2.2\",\n  \"ItemId\": \"Blue Warrior\",\n  \"CharacterName\": \"FighterDude\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "CharacterId": "98765432",
    "CharacterType": "Blue Warrior",
    "Result": true
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

PlayFab API

PlayFab REST API References

將角色授與使用者

Error codes

授權

主體

回應