Update

The Update() method calls an API asking to perform an updating operation on the Database table the API works with.

Result The UniREST Server application will update an exiting record and reply with a confirmation. Since this operation requires identifying a specific, existing record (also more records) inside a table, you must always provide the necessary Keys.

_ = #UniRESTClient.Async#.$Update$(%api, tableData, callBack%, ^fieldsToUpdate^);

api|string
The API address, under the API class.
__
tableData|object
Optional values to send to the server. It must be an instance of the table class in use.
__
callBack|Action<TABLE[]>
The function to call on operation completed.
__
fieldsToUpdate|(string)
The list of columns to update, separated by a space.

bool
true if the operation is completed, false if a system error occurred.

fieldsToUpdate parameter

By default, the Update() method updates all the record’s columns set as “Update” with the provided tableData object. This means, that you should always provide all the requested values accordingly with your API configuration.

For example, if you set your API as the screenshot below, you’re saying that the Update operation has to change the value of the columns “name”, “health” and “strength”, while the column “creation_date” must be excluded as if it was unexisting.

However, often happens that you don’t want to be limited by the API configuration and, instead, you want to be free to update just one or two columns depending on what you need at that time. In this case, you can let all the API’s columns set to “Update” and use the Update() method setting the fieldsToUpdate parameter, so as to specify what exactly are the columns you want to update. The API will update only the columns you listed in that parameter.

_ = UniRESTClient.Async.Update(
     API.player_data, 
     new DB.Players
     {
         id = UniRESTClient.UserID,
         name = "Conan",
         health = 800            
     },
     (bool ok) => 
     {
         // Some code here...
     },
     "name health"
);

In this example, the columns “name” and “health” will be updated (the id is used to find the record to update), whereas the columns “strength” and “creation_date” will be ignored.

Example

“Players” Database table
In this table, each record is a single player with its characteristics.

“player/data” API
This API updates the player data. To identify the player record it’s necessary to use the record ID, so the “ID as Key” option has been checked. Moreover, the creation_date column has been set to “None” because we don’t want to have it updated.

Update() method
In this example, the Update() method calls the API.player_data sending all the data the API expects to receive. The callBack will return true if the record if the operation is complete, false otherwise. You can use the DBResponse property to know if the updating really worked.

_ = UniRESTClient.Async.Update(
     API.player_data, 
     new DB.Players
     {
         id = UniRESTClient.UserID,
         name = "Conan",
         health = 800,
         strength = 50           
     },
     (bool ok) => 
     {
         if (ok && UniRESTClient.DBResponse > 0)
         {
             Debug.Log("Updated!");
         }
         else
         {
             Debug.Log("Updating failed");
         }
     },
     "name health"
);

“Players” Database table
The table has been updated with the new values.

CAN WRITE (Update feature)

In the MySQL system, writing and updating operations are managed separately by two different queries statement (INSERT and UPDATE). In those scenarios where you have to work on a single record, the ordinary procedure is to write a record (insert), get his ID and perform the updates (update) using that ID.

The UniREST Server application has a feature that allows using an API both to write and update a single record (a single record only!) with one call through the Update() method. To use this feature you must check the “Can Write” API option.

Example

“weapons/add” API
For activating this feature, the API’s Update operation must have:

• the “Can Write” option checked;
• at least one column set as “Key” (in this example, player_id).

The use of the Update() method doesn’t change because the writing feature is set in the API configuration. The player_id will be used to check if the Weapon table already contains a record with player_id equal to the User ID.

_ = UniRESTClient.Async.Update(
     API.weapons_add,
     new DB.Weapon
     {
         player_id = UniRESTClient.UserID,
         name = "Axe",
         attack = 1000          
     },
     (bool ok) =>
     {
         // Somme code here...
     }
);

When this API is called by the Update() method, the UniREST Server application checks if a record with the given player_id already exists in the Weapon table. If this record doesn’t exist, a new record is created. Whereas, the existing record is updated.

---

---

Tips

The use of the Update() method can be tricky: if it’s not perfectly used both in the API and in Unity, it won’t work.

Firstly, in general, the Update() method requires a minimum 3 pieces of information (so, if looking at your C# script you see only one or two pieces of information, this means there’s something wrong):

1. the table where to perform the updating;
2. the value or the values to update;
3. how to locate the specific record you want to update.

One of the most common reasons why the Update() method fails is because something is missing in the point n. 3. This point is a little bit tricky because it requires:

• to include the values for the “record locating rules” together with the values you want to update, and this, sometimes, can raise some confusion;
• to configure the Update API with the proper Keys.

Example

You have a table named MyTable and an API called myapi/test. This API is configured in this way:

Error n.1

_ = UniRESTClient.Async.Update(
     API.myapi_test,
     new DB.MyTable
     {
         name = "Conan",
         health = 1000,
         strength = 5000    
     },
     (bool ok) => { . . . }
);

A code like this one can look correct at the first sight. Instead, it contains a common error. You have correctly set the table’s name, the API to call and the values to update, but there are no instructions on how to find the record to update. So, the Server knows what columns to update and where, but doesn’t know which specific record to update.

The API is configured with the ID as Key option selected, so the Update expects to locate the record using the ID value. If, for example, the record ID corresponds to the logged-in user ID, the right C# code is:

_ = UniRESTClient.Async.Update(
     API.myapi_test,
     new DB.MyTable
     {
            name = "Conan",
            health = 1000,
            strength = 5000,
            id = UniRESTClient.UserID // <- this was missing 
     },
     (bool ok) => { . . . }
);

---

Error n.2

_ = UniRESTClient.Async.Update(
     API.myapi_test,
     new DB.MyTable
     {
         name = "Conan",
         health = 1000,
         id = UniRESTClient.UserID        
     },
     (bool ok) => { . . . }
);

This C# script looks correctly configured: it has the table’s name, the API to call, the values to update and the id for locating the record. Instead, it won’t work. This is because the API configuration has the strength column set to Update and all the columns set to Update are mandatory. You can change the strength column settings to None or change your C# script:

_ = UniRESTClient.Async.Update(
     API.myapi_test,
     new DB.MyTable
     {
         name = "Conan",
         health = 1000,
         strength = 5000,  // <- this was missing!!!
         id = UniRESTClient.UserID        
     },
     (bool ok) => { . . . }
);

// Or you can use the fieldsToUpdate parameter if you don't want to update the strength value:

_ = UniRESTClient.Async.Update(
     API.myapi_test,
     new DB.MyTable
     {
         name = "Conan",
         health = 1000,
         id = UniRESTClient.UserID        
     },
     (bool ok) => { . . . },
     "name health" // <- this will allow you to update name and health only 
                   //     even if strength would be mandatory!
);

---

Error n. 3

The API now is configured in this way:

_ = UniRESTClient.Async.Update(
     API.myapi_test,
     new DB.MyTable
     {
         name = "Conan",
         health = 1000,
         strength = 5000
     },
     (bool ok) => { . . . }
);

This C# script won’t work. Even if the name column has been set to Key and the value “Conan” will be used to find the record to update, the API configuration still has the ID as Key option selected. All the defined Keys must be provided in the Update() method:

_ = UniRESTClient.Async.Update(
     API.myapi_test,
     new DB.MyTable
     {
         name = "Conan", // <- this will be used to find the record to update!
         health = 1000,
         strength = 5000,  
         id = UniRESTClient.UserID // <- this will be used to find the record to update too!
     },
     (bool ok) => { . . . }
);

Note that the code above will use name and id as rules for locating the record to update.

If instead, you wanted to use just the name column for locating the record, you must unselect the ID as Key option so as to have only the name column as a Key:

_ = UniRESTClient.Async.Update(
     API.myapi_test,
     new DB.MyTable
     {
         name = "Conan", // <- this is the only Key you need!
         health = 1000,
         strength = 5000
     },
     (bool ok) => { . . . }
);