如何在 Unity 呼叫 GraphQL 的 API？

GanniPiece

前言

GraphQL 是 Facebook(現改名為 Meta) 所維護的 API 與資料的查詢語言的開發環境。不同於過往使用 RESTful API 進行資料查詢，需要透過多次的來回，GraphQL 可以更有彈性的查詢資料。所有的資料間有如圖形一般，可以大幅減少 Request 的成本。 在 python 上我們可以透過 graphene1 的函式庫，來作為我們與 GraphQL API 溝通的橋樑。那麼，同樣在 Unity 上我們可以透過 graphQL-client-unity 來與之互動。

gazuntype/graphQL-client-unity: This repository houses a unitypackage that can be included in your Unity Project to enable it communicate with a graphQL server. (github.com)

在接下來的文章中，我們就會來看如何安裝該套件，並使用期呼叫 GraphQL API。

安裝

  1. 在 graphQL-client-unity 的 Github 頁面中，找到名為 UnityPackages 的資料夾，並將該資料夾下的 .unitypackage 檔案下載。

  2. 開啟 Unity 專案，並將 步驟 1. 下載的 .unitypackage(graphQl-client-unity-v2.unitypackage)匯入

  3. 安裝相關依賴

    3.1 Async Await Support | Integration | Unity Asset Store 2

    3.2 JSON .NET For Unity | Input Management | Unity Asset Store 3

在 macOS 上安裝完上述套件後，發現 Unity 仍出現以下錯誤：

PrecompiledAssemblyException: Multiple precompiled assemblies with the same name Newtonsoft.
Json.dll included on the current platform. Only one assembly with the same name is allowed ?
per platform.

由錯誤訊息得知不能同時存在多個 Newtonsoft.Json.dll 的檔案。
我們發現 Asset/JsonDotNet/Assemblies 底下的兩個資料夾 Standalone/ 與 Windows/ 有相同名稱檔案。端看使用者平台，選擇其一留下並將其他刪除即可解決。

使用教學

以下我們以 Pokemon GraphQl 的 API 作為示例，說明如何創建 API reference，並創建及呼叫 graphQL 中的 query, mutation, subscription 等功能。

創立新的 API Reference

  1. 在 Assets 資料夾中，點擊右鍵選擇 Create -> GraphQLClient -> API Reference 新增一份 Scriptable Object

  2. 為此 Scriptable Object 命名

建立 Query, Mutation, Subscription

三者的加入方式雷同，以下以 Query 作為示例。

Note: 我們需要點擊 Introspect 的按鈕來確保與當前 API 的 schema 保持同步

  1. 輸入 API 的網址 e.g. https://graphql-pokemon.now.sh/

  2. 點擊 Introspect 進行同步

  3. 點擊 Create New Query 新增 Query

  4. 輸入 Query 名稱 e.g. GetAllPokemon

  5. 點擊 Create Field 新增 query 的欄位

  6. 透過 Preview Query 來對設定進行預覽

呼叫 API

我們可以在 script 中使用上面建立好的 Scriptable Object。

  1. 首先我們要在 script 中新增一個 GraphApi 的物件

    1using GraphQlClient.Core;
2
3public GraphApi pokemonReference;

  2. 接著，將方才建立的 Scriptable Object 於 Inspector 中拉入 script

  3. 透過 Post 函式呼叫 API

    1public async void GetPokemons()
2{
3    UnityWebRequest request = await pokemonReference.Post(
4        "GetAllPokemons", GraphApi.Query.Type.Query
5    );
6}

  4. 回傳值為 UnityWebRequest 的物件，我們可以以下方法得到所需的資料

    1string data = request.downloadHandler.text;

回傳值為 JSON 的格式，可以透過 [JsonUtility class] 或第三方的 Json parser 諸如 JSON. Net For Unity 3 來進行處理

動態設定輸入

我們也可以在 script 中動態的改變 query 的欄位。此做法是透過 Query.SetArgs(object input) 來實現。

 1public async void CreateNewUser()
 2{
 3    GraphApi.Query createUser = userApi.GetQueryByName(
 4                                    "CreateNewUser",
 5                                    GraphApi.Query.Type.Mutation);
 6    createUser.SetArgs(
 7        new{objects = new{id = "idGiven", name = "nameGiven"}});
 8
 9    UnityWebRequest request = await userApi.Post(createUser);
10}

我們可以建立一個 async 的函式 CreateNewUser 作為創立新使用者的方法。在 line 3 中我們同 Query 時相同，先取得一個 Mutation 形式的 API 服務。接著，line 6 中，我們將 id 與 name 作為欄位進行輸入參數的設定。最後在 line 9 中再透過 Post 送出這個 Mutation 的請求。

小結

在這篇文章中，我們使用了 graphQl-unity-client 的這個插件，來幫助我們在 Unity 上有效的呼叫 graphQl 的 API。我們講解了如何安裝此套件，包含第三方套件的安裝，並排除過程可能會遇到的錯誤。另外，也簡單的介紹了該套件的使用方式，並完成基本的 query, mutation 等的操作。

  1. Graphene-Python ↩︎

  2. Async Await Support | Integration | Unity Asset Store ↩︎

  3. Newtonsoft Json Unity Package | Newtonsoft Json | 2.0.2 (unity3d.com) ↩︎ ↩︎