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

# Python 快速入门

> 安装 PlayFab Python 3 SDK，并从原生 Python 脚本进行首次 PlayFab API 调用，用于管理工具或游戏引擎集成。

本快速入门旨在帮助您在 Python 3 中进行首次 API 调用。

原生 Python 项目可以有几种用途：

* 作为独立的控制台管理工具来维护您的游戏。
* 集成到现有的基于 Python 的游戏引擎中。
  * 有关 Python 游戏引擎的列表，请参阅 python.org 网站上的 [PythonGameLibraries](https://wiki.python.org/moin/PythonGameLibraries)。

## 先决条件

* 一个 [PlayFab 开发者帐户](https://developer.playfab.com)。
* 在您的系统上安装 [Python 3](https://www.python.org/downloads/)。
  * 您还必须安装 requests 模块。

<Note>
  Python SDK 的此 Beta 版本仅支持同步 API 调用，您的游戏循环可能会在执行 PlayFab API 调用时被阻塞。您可能需要创建自己的异步/线程模型来避免此问题。
</Note>

如果您在调试问题时遇到困难，且所提供的错误信息不够详细，请访问我们的 [PlayFab 论坛](https://community.playfab.com/index.html)。

## Python 项目设置

1. 在命令提示符中，使用以下命令安装 [PlayFab 包](https://pypi.org/project/playfab/)。

```cmd theme={null}
pip install playfab
```

如果 `pip` 不在您的路径中，请改用以下命令。

```cmd theme={null}
python -m pip install playfab
```

2. 在您的项目目录中，创建一个名为 playfab\_test.py 的 Python 脚本。

## 设置您的首次 API 调用

本快速入门提供了进行首次 PlayFab API 调用所需的最少步骤，没有任何 GUI 或屏幕反馈。确认通过控制台打印语句完成。

将您的 playfab\_test.py 文件的内容替换为下面显示的内容。

```python theme={null}
from playfab import PlayFabClientAPI, PlayFabSettings

PlayFabSettings.TitleId = "144"

request = {
    "CustomId": "GettingStartedGuide",
    "CreateAccount": True
}

def callback(success, failure):
    if success:
        print("Congratulations, you made your first successful API call!")
    else:
        print("Something went wrong with your first API call.  :(")
        if failure:
            print("Here's some debug information:")
            print(failure.GenerateErrorReport())
PlayFabClientAPI.LoginWithCustomID(request, callback)
```

## 完成并执行

使用下面显示的命令运行 Python 脚本。

```cmd theme={null}
python playfab_test.py
```

完成后，您应该会看到以下文本："Congratulations, you made your first successful API call!"

此时，您可以开始进行其他 API 调用并构建您的游戏。有关所有可用客户端 API 调用的列表，请参阅我们的 [PlayFab API 参考](/services/playfab/api-references) 文档。

编码愉快！

## 代码解析

此可选的最后一部分详细描述了 playfab\_test.py 的每个部分。

* Imports
  * PlayFab 导入使您能够访问 API。

* `PlayFabSettings.TitleId = "144"`
  * 每个 PlayFab 开发者都会在 Game Manager 中创建一个游戏。当您发布游戏时，必须将该 titleId 编入游戏代码中。这可以让客户端知道如何访问 PlayFab 中的正确数据。对于大多数用户，将其视为使 PlayFab 正常运行的必要步骤。

* request
  * 大多数 PlayFab API 方法都需要输入参数，而这些输入参数被打包到字典对象中。
    * `LoginWithCustomIDRequest` 接受强制参数 `CustomId`，它唯一标识玩家并返回相关联的实体令牌；以及 `CreateAccount`，允许通过此调用创建新帐户。
    * 对于登录，大多数开发者可能希望使用更合适的登录方法。
      * 请参阅 [PlayFab 登录文档](xref:titleid.playfabapi.com.client.authentication) 以获取所有登录方法和输入参数的列表。常见选择包括：
        * [LoginWithAndroidDeviceID](xref:titleid.playfabapi.com.client.authentication.loginwithandroiddeviceid)
        * [LoginWithIOSDeviceID](xref:titleid.playfabapi.com.client.authentication.loginwithiosdeviceid)
        * [LoginWithEmailAddress](xref:titleid.playfabapi.com.client.authentication.loginwithemailaddress)

* 回调
  * Success
    * 如果 API 调用成功，success 将包含请求的信息，failure 将为 `None`。
    * 对于登录请求，success 将包含有关玩家的基本信息，但对于大多数用户，登录只是调用其他 API 之前的必要步骤。

  * Failure
    * 如果 API 调用未成功，failure 将包含一些错误信息，success 将为 `None`。
    * API 调用可能因多种原因失败，您应始终尝试处理失败。
    * API 调用失败的原因（按可能性排序）
      * `PlayFabSettings.TitleId` 未设置。如果您忘记将 `titleId` 设置为您的游戏，则一切都无法正常工作。
      * 请求参数。如果您没有为特定 API 调用提供正确或必需的信息，则该调用将失败。
      * 设备连接问题。手机不断失去/恢复连接，因此任何时候的 API 调用都可能随机失败，然后紧接着又成功。进入隧道可能会让您完全断开连接。
      * PlayFab 服务器问题。与所有软件一样，可能会出现问题。有关更新信息，请参阅我们的[发行说明](/services/playfab/release-notes)。
      * 互联网并非 100% 可靠。有时消息会损坏或无法到达 PlayFab 服务器。

* `PlayFabClientAPI.LoginWithCustomID`
  * 同步触发 API 调用。完成后，将调用回调。


## Related topics

- [PlayFab 支持的语言](/zh-CN/services/playfab/sdks/languages/index.md)
- [快速入门](/zh-CN/services/playfab/economy-monetization/economy-v2/quickstart.md)
- [Android 快速入门](/zh-CN/services/playfab/sdks/c/quickstart-android.md)
- [iOS 快速入门](/zh-CN/services/playfab/sdks/c/quickstart-ios.md)
- [Linux 快速入门](/zh-CN/services/playfab/sdks/c/quickstart-linux.md)