> ## 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 參考](/zh-TW/services/playfab/api-references)文件。

祝您程式撰寫愉快！

## 解構程式碼

這個選擇性的最後一節會詳細說明 playfab\_test.py 的每個部分。

* 匯入
  * 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)

* 回呼
  * 成功
    * 如果 API 呼叫成功，success 會包含所要求的資訊，而 failure 會是 `None`。
    * 對於登入要求，success 會包含玩家的基本資訊，但對大多數使用者而言，登入只是呼叫其他 API 之前的必要步驟。

  * 失敗
    * 如果 API 呼叫不成功，failure 會包含一些錯誤資訊，而 success 會是 `None`。
    * API 呼叫可能因許多原因而失敗，您應該一律嘗試處理失敗情況。
    * API 呼叫失敗的原因 (依可能性排序)
      * 未設定 `PlayFabSettings.TitleId`。如果您忘記將 `titleId` 設定為您的遊戲，則一切都無法運作。
      * 要求參數。如果您沒有為特定 API 呼叫提供正確或必要的資訊，呼叫就會失敗。
      * 裝置連線問題。行動電話會不斷失去/恢復連線，因此任何 API 呼叫都可能隨時隨機失敗，然後又立即恢復正常。進入隧道可能會讓您完全中斷連線。
      * PlayFab 伺服器問題。就像所有軟體一樣，可能會發生問題。如需更新資訊，請參閱我們的[版本資訊](/zh-TW/services/playfab/release-notes)。
      * 網際網路並非 100% 可靠。有時訊息會損毀或無法送達 PlayFab 伺服器。

* `PlayFabClientAPI.LoginWithCustomID`
  * 以同步方式觸發 API 呼叫。完成時，會叫用回呼。


## Related topics

- [PlayFab 支援的語言](/zh-TW/services/playfab/sdks/languages/index.md)
- [快速入門](/zh-TW/services/playfab/economy-monetization/economy-v2/quickstart.md)
- [Party 快速入門](/zh-TW/services/playfab/multiplayer/networking/quickstart.md)
- [Android 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-android.md)
- [GDK 快速入門](/zh-TW/services/playfab/sdks/c/quickstart-gdk.md)