Item
第 4 章 物品處理
4-1 認識遊戲物品
物品(Item)其實就是 SGC 專為線上遊戲所規劃的資料庫服務，依照用途分為三種：
- 商品 (Goods)
商品是遊戲中的寶物或道具，可用來在遊戲內販售，也可以透過Android & IOS平台的內購服務來購買此商品。 - 性質 (Property)
用來讓開發者存放性質的地方，可以用來描述玩家在遊戲中的某些特性，例如:身高、體重等。功能與資料相同，但可以透過SGC的API與資料做區別。 - 資料 (Data)
用來讓開發者存放資料的地方，例如:伺服器的版本號、官方網站的Url等。功能與性質相同，但可以透過SGC的API與性質做區別。
請注意，玩家擁有哪些物品、內容是什麼，這些對其他玩家都是不公開的。以下是玩家與個人後台，對於不同類型物品的可見程度：
| 物品類型 | SGC 網站後台 |
|---|---|
| 商品(Goods | 可見 |
| 性質(Property) | 可見 |
| 資料(Data) | 不可見 |
4-2 物品管理
物品必須先在 SGC 遊戲管理後台定義，取得物品的 IGUID (Item GUID)後才能在程式中存取。建立新物品時必須填寫以下表單：
表單欄位說明如下：
- 名稱
物品的名稱。 - 說明
物品的詳細說明。 - 類型
分為商品(Goods)、性質(Property)、資料(Data)三種。 - 公開
分為公開與不公開兩種。 - 效期 分為永久有效、固定時間內有效、固定日期前有效三種。
- 物品屬性
「物品屬性」是由「屬性名稱」與「屬性值」形成的配對，每個物品可以設定好幾筆屬性資料， 當物品被實例化時，此處所設定的屬性值則是實例物品的預設值。有關於物品實例的詳細說明，請參考下一小節。
物品建立之後，開發者可以再回來物品頁面查看它的 IGUID，這是呼叫 SGC 物品 API 所需要的參數資料。
4-3 物品處裡程式
物品處理的 API 函式都在 CloudItem 類別中，此類別是由靜態函式組成，沒有建構子(Constructor)， 也沒有物件屬性(Property)，程式設計師要進行與物品相關的處理，請直接叫用這些函式。
接下來所介紹的 API 函式，以下一節的 GetItemClass()為例，程式設計師呼叫時要在前面加上「CloudItem.」，就像這個樣子：
CloudItem.GetItemClass();
4-4 取得特定物品類別(Class)的資料
當開發者在管理後台建立物品後，該物品的類別(Class)就已經建立。由於物品類別的內容對所有玩家來說都是一樣的，所以任何玩家透過 API 函式取得的物品類別的資訊也都會一樣。讀取物品類別的定義資料請使用 GetItemClass()，它的函數定義如下：
static void GetItemClass(CloudGame game, string iguid, OnCallCompletionWithData cb, object token)
參數 cb 是 callback 函式，開發者必須自行撰寫，函式的定義如下：
cb(int code, object data, object token)
當 GetItemClass()成功取得物品的定義資料時，系統會呼叫開發者自定的 callback，同時傳入 code為零的參數，反之若是作業失敗，code 則為非零。
取得的物品資料放在 callback 的參數 data 裡，存取時先轉型為 List <Hashtable>，不過 List 中只會有一個元素。Hashtable 共有以下 key 值，代表的是物品的定義資料：
| Key | Value | Value 的型別 |
|---|---|---|
| iguid | 物品的 IGUID | string |
| name | 物品的名稱 | string |
| desc | 物品的描述 | string |
| type | 物品類型 1.商品、2.性質、3.資料 | int |
| now | 目前伺服器的系統時間，格式為yyyy/MM/dd HH:mm:ss，時區為 UTC |
string |
| attr | 1.屬性如果這個物品沒有設定屬性，則 Value 為 null。 2.屬性資料為 key=value 以 List Hashtable 存放。3.Hashtable 有兩個 Key:name 屬性名稱、value 屬性值 | List Hashtable |
4-5 列舉已建立之物品類別(Class)資料
GetItemClass() 有另外一個多載函式可也列舉(Enumerate)已建立的物品類別：
static void GetItemClass(CloudGame game,int option, OnCallCompletionWithData cb, object token)
和先前指定 IGUID 查詢特定物品類別不同的是參數 option，依照 option 值的不同，可以查詢不同類型的物品類別：
| option | 物品類型 |
|---|---|
| 0 | 所有的「性質」物品 |
| 1 | 所有的「商品」物品 |
| 2 | 所有的「性質」和「商品」物品 |
| 3 | 所有的「資料」物品 |
查詢後所列舉物品資料將以 callback 函式傳回，型態為 List <Hashtable>，List 中元素就是每一個物品類型的資料。詳細的 List 與 Hashtable 格式的說明請參考上一節。
4-6 物品實例(Instance)
物品類別是所有玩家所共用，物品實例由物品類別產生，也就是經過實例化的過程，產生個別玩家所擁有的物品。
玩家可以建立與刪除物品實例，也可以讀取與修改屬性資料，這些操作都只是在處理個人所擁有的物品，並不會影響到別的玩家的物品。我們可以想像物品實例其實就是物品的複本(Copy)，玩家所建立的複本是玩家所個別擁有的，玩家們的複本彼此之間不會互相干擾。
(1) 新增物品實例
玩家要擁有物品實例，首先要建立實例，使用的函數定義如下：
static void NewItemInstance(CloudGame game, string iguid, OnCallCompletionWirhData cb, object token)
其中參數 iguid 就是要新增的物品之 IGUID，callback 函式的定義如下：
void cb(int code, object id, object token)
當 code 為 0 時，表示物品實例已經建立成功，同時 id 為該物品實例之 Instance ID，請將 id 改型為 string；反之，若 code 為非 0 時，表示作業失敗。
請注意，同一個物品類別是可以建立多個物品實例的，每次呼叫 NewItemInstance()就會建立一個新的實例，辨識不同物品實例得靠它們的 Instance ID，必要時程式設計師必須設法儲存個別物品實例的 Instance ID。
(2) 刪除物品實例
刪除物品實例使用的函數如下：
static void DeleteItemInstance(CloudGame game, string iguid, string id, OnCallCompletion cb, object token)
參數 id 就是要刪除的物品實例的 instance id。
callback 函式定義：
void cb(int code, object token)
當 code 為 0 時，表示物品實例已經成功的被刪除了，反之若 code 非 0 時，表示刪除作業失敗。
(3) 讀取物品屬性
指定物品的 IGUID 與物品實例的 Instance ID 就可以讀取該實例的屬性資料，讀取物品屬性的函式定義如下：
static void GetItemInstanceAttribute(CloudGame game, string iguid, string id, string attrName,OnCallCompletionWithData cb, object token)
當中的參數 id 就是物品的 Instance ID，attrName 就是要讀取的屬性名稱。
函式執行完成後觸發的 callback cb 的定義如下：
void cb(int code, object obj, object token)
當 code 為零時表示成功，非零表示失敗。如果是執行成功，請將參數 obj 改型(case)為Hashtable， 共有以下 Key 值，代表的屬性的資料：
| Key | 說明 |
|---|---|
| name | 屬性名稱，也就是參數attrName |
| value | 屬性值 |
| stamp | 寫入此屬性的時間 |
| now | 目前伺服器的系統時間，格式為yyyy/MM/dd HH:mm:ss，時區為 UTC |
(4) 修改物品屬性
修改已建立實例的物品則是使用 SetIemInstanceAttribute() 函式，定義如下：
void SetItemInstanceAttribute(CloudGame game, string iguid, string id, string attrName, string attrValue, OnCallCompletion cb, object token)
參數 id 就是要刪除的物品實例的 instance id，attrName 就是要修改的屬性名稱，attrValue 就是屬性修改後的值。
函式執行完成後觸發的 callback cb 的定義如下：
void cb(int code, object token)
當 code 為零時表示成功，非零表示失敗。
4-7 In-App Purchase 與 In-App Billing
In-App Purchase 是 iOS 設備的 App 應用程式內直接購買商品的機制，有兩種做法：
- Build-in Product Delivery 這是一種不安全的交易方式，在此略過。
- Server Product Delivery
流程中的(1)到(9)步驟，開發者必須透過 XCODE 製作程式，詳細內容請參考 iOS Developer 網站。在取得交易收據「receipt-data」後，透過 SGC 所提供伺服器執行步驟(10)至(14)，以驗證 receipt-data 是否為合法交易的收據資料。
驗證方法很簡單，只要呼叫 CloudShop.CommitInAppPurchase()即可，函式定義如下：public static void CommitInAppPurchase(CloudGame game, string iguid, int type, string receipt, OnCallCompletion cb, object token)參數type指定購買方式，0 為 sandbox(測試用)，1 則為實際購買。
參數 receipt 就是從 App-Store 中傳回的交易收據資料(receipt-data)。驗證完成後將會呼叫 callback 函式 cb，其函式定義為：
void cb(int code)
驗證成功，code 為 0；反之，失敗則 code 為非 0。
除了 iOS 外，Android 系統也有內置購買服務，由於 Android 市集不像 iOS 只有 Apple 獨家提供，目前 SGC 支援 Goole 官方提供的 Google Play 市集的內置購買之收據驗證服務，開發者只要將購買完成後取得的收據資料透過 CloudShop.CommitInAppBilling()函式提交，驗證無誤後系統為此商品新增一個物件實例。函式定義如下：
public static void CommitInAppBilling(CloudGame game, string iguid, int type, string receipt, string signature, OnCallCompletion cb, object token)
由於 Google Play 除了會傳回收據資料以外，還會有個電子簽章資料，都要一併提交驗證，因此這個函式多了個 signature 參數，其餘用法都和 iOS 的 CommitInAppPurchase()函式一樣。