feat(VisualRecognitionV4): add support to get training usage data

Author: mamoonraja

Scripts/Services/VisualRecognition/V4/Model/Image.cs

@@ -15,6 +15,7 @@
 *
 */
 
+using System.Collections.Generic;
 using Newtonsoft.Json;
 
 namespace IBM.Watson.VisualRecognition.V4.Model
@@ -40,9 +41,9 @@ public class Image
         [JsonProperty("objects", NullValueHandling = NullValueHandling.Ignore)]
         public DetectedObjects Objects { get; set; }
         /// <summary>
-        /// Details about an error.
+        /// A container for the problems in the request.
         /// </summary>
         [JsonProperty("errors", NullValueHandling = NullValueHandling.Ignore)]
-        public Error Errors { get; set; }
+        public List<Error> Errors { get; set; }
     }
 }

Scripts/Services/VisualRecognition/V4/Model/ImageDetails.cs

@@ -15,6 +15,7 @@
 *
 */
 
+using System.Collections.Generic;
 using Newtonsoft.Json;
 using System;
 
@@ -51,10 +52,10 @@ public class ImageDetails
         [JsonProperty("dimensions", NullValueHandling = NullValueHandling.Ignore)]
         public ImageDimensions Dimensions { get; set; }
         /// <summary>
-        /// Details about an error.
+        /// Gets or Sets Errors
         /// </summary>
         [JsonProperty("errors", NullValueHandling = NullValueHandling.Ignore)]
-        public Error Errors { get; set; }
+        public List<Error> Errors { get; set; }
         /// <summary>
         /// Training data for all objects.
         /// </summary>

Scripts/Services/VisualRecognition/V4/Model/TrainingEvent.cs

@@ -0,0 +1,84 @@
+/**
+* Copyright 2018, 2019 IBM Corp. All Rights Reserved.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*      http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*
+*/
+
+using Newtonsoft.Json;
+using System;
+
+namespace IBM.Watson.VisualRecognition.V4.Model
+{
+    /// <summary>
+    /// Details about the training event.
+    /// </summary>
+    public class TrainingEvent
+    {
+        /// <summary>
+        /// Trained object type. Only `objects` is currently supported.
+        /// </summary>
+        public class TypeValue
+        {
+            /// <summary>
+            /// Constant OBJECTS for objects
+            /// </summary>
+            public const string OBJECTS = "objects";
+            
+        }
+
+        /// <summary>
+        /// Training status of the training event.
+        /// </summary>
+        public class StatusValue
+        {
+            /// <summary>
+            /// Constant FAILED for failed
+            /// </summary>
+            public const string FAILED = "failed";
+            /// <summary>
+            /// Constant SUCCEEDED for succeeded
+            /// </summary>
+            public const string SUCCEEDED = "succeeded";
+            
+        }
+
+        /// <summary>
+        /// Trained object type. Only `objects` is currently supported.
+        /// Constants for possible values can be found using TrainingEvent.TypeValue
+        /// </summary>
+        [JsonProperty("type", NullValueHandling = NullValueHandling.Ignore)]
+        public string Type { get; set; }
+        /// <summary>
+        /// Training status of the training event.
+        /// Constants for possible values can be found using TrainingEvent.StatusValue
+        /// </summary>
+        [JsonProperty("status", NullValueHandling = NullValueHandling.Ignore)]
+        public string Status { get; set; }
+        /// <summary>
+        /// Identifier of the trained collection.
+        /// </summary>
+        [JsonProperty("collection_id", NullValueHandling = NullValueHandling.Ignore)]
+        public string CollectionId { get; set; }
+        /// <summary>
+        /// Date and time in Coordinated Universal Time (UTC) that training on the collection finished.
+        /// </summary>
+        [JsonProperty("completion_time", NullValueHandling = NullValueHandling.Ignore)]
+        public DateTime? CompletionTime { get; set; }
+        /// <summary>
+        /// The total number of images that were used in training for this training event.
+        /// </summary>
+        [JsonProperty("image_count", NullValueHandling = NullValueHandling.Ignore)]
+        public long? ImageCount { get; set; }
+    }
+}

Scripts/Services/VisualRecognition/V4/Model/TrainingEvent.cs.meta

@@ -0,0 +1,57 @@
+/**
+* Copyright 2018, 2019 IBM Corp. All Rights Reserved.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*      http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*
+*/
+
+using System.Collections.Generic;
+using Newtonsoft.Json;
+using System;
+
+namespace IBM.Watson.VisualRecognition.V4.Model
+{
+    /// <summary>
+    /// Details about the training events.
+    /// </summary>
+    public class TrainingEvents
+    {
+        /// <summary>
+        /// The starting day for the returned training events in Coordinated Universal Time (UTC). If not specified in
+        /// the request, it identifies the earliest training event.
+        /// </summary>
+        [JsonProperty("start_time", NullValueHandling = NullValueHandling.Ignore)]
+        public DateTime? StartTime { get; set; }
+        /// <summary>
+        /// The ending day for the returned training events in Coordinated Universal Time (UTC). If not specified in the
+        /// request, it lists the current time.
+        /// </summary>
+        [JsonProperty("end_time", NullValueHandling = NullValueHandling.Ignore)]
+        public DateTime? EndTime { get; set; }
+        /// <summary>
+        /// The total number of training events in the response for the start and end times.
+        /// </summary>
+        [JsonProperty("completed_events", NullValueHandling = NullValueHandling.Ignore)]
+        public long? CompletedEvents { get; set; }
+        /// <summary>
+        /// The total number of images that were used in training for the start and end times.
+        /// </summary>
+        [JsonProperty("trained_images", NullValueHandling = NullValueHandling.Ignore)]
+        public long? TrainedImages { get; set; }
+        /// <summary>
+        /// The completed training events for the start and end time.
+        /// </summary>
+        [JsonProperty("events", NullValueHandling = NullValueHandling.Ignore)]
+        public List<TrainingEvent> Events { get; set; }
+    }
+}

Scripts/Services/VisualRecognition/V4/Model/TrainingEvents.cs

@@ -900,7 +900,9 @@ private void OnDeleteImageResponse(RESTConnector.Request req, RESTConnector.Resp
         /// <param name="callback">The callback function that is invoked when the operation completes.</param>
         /// <param name="collectionId">The identifier of the collection.</param>
         /// <param name="imageId">The identifier of the image.</param>
-        /// <param name="size">Specify the image size. (optional, default to full)</param>
+        /// <param name="size">The image size. Specify `thumbnail` to return a version that maintains the original
+        /// aspect ratio but is no larger than 200 pixels in the larger dimension. For example, an original 800 x 1000
+        /// image is resized to 160 x 200 pixels. (optional, default to full)</param>
         /// <returns><see cref="byte[]" />byte[]</returns>
         public bool GetJpegImage(Callback<byte[]> callback, string collectionId, string imageId, string size = null)
         {
@@ -1115,6 +1117,85 @@ private void OnAddImageTrainingDataResponse(RESTConnector.Request req, RESTConne
                 ((RequestObject<TrainingDataObjects>)req).Callback(response, resp.Error);
         }
         /// <summary>
+        /// Get training usage.
+        ///
+        /// Information about the completed training events. You can use this information to determine how close you are
+        /// to the training limits for the month.
+        /// </summary>
+        /// <param name="callback">The callback function that is invoked when the operation completes.</param>
+        /// <param name="startTime">The earliest day to include training events. Specify dates in YYYY-MM-DD format. If
+        /// empty or not specified, the earliest training event is included. (optional)</param>
+        /// <param name="endTime">The most recent day to include training events. Specify dates in YYYY-MM-DD format.
+        /// All events for the day are included. If empty or not specified, the current day is used. Specify the same
+        /// value as `start_time` to request events for a single day. (optional)</param>
+        /// <returns><see cref="TrainingEvents" />TrainingEvents</returns>
+        public bool GetTrainingUsage(Callback<TrainingEvents> callback, string startTime = null, string endTime = null)
+        {
+            if (callback == null)
+                throw new ArgumentNullException("`callback` is required for `GetTrainingUsage`");
+
+            RequestObject<TrainingEvents> req = new RequestObject<TrainingEvents>
+            {
+                Callback = callback,
+                HttpMethod = UnityWebRequest.kHttpVerbGET,
+                DisableSslVerification = DisableSslVerification
+            };
+
+            foreach (KeyValuePair<string, string> kvp in customRequestHeaders)
+            {
+                req.Headers.Add(kvp.Key, kvp.Value);
+            }
+
+            ClearCustomRequestHeaders();
+
+            foreach (KeyValuePair<string, string> kvp in Common.GetSdkHeaders("watson_vision_combined", "V4", "GetTrainingUsage"))
+            {
+                req.Headers.Add(kvp.Key, kvp.Value);
+            }
+
+            req.Parameters["version"] = VersionDate;
+            if (!string.IsNullOrEmpty(startTime))
+            {
+                req.Parameters["start_time"] = startTime;
+            }
+            if (!string.IsNullOrEmpty(endTime))
+            {
+                req.Parameters["end_time"] = endTime;
+            }
+
+            req.OnResponse = OnGetTrainingUsageResponse;
+
+            Connector.URL = GetServiceUrl() + "/v4/training_usage";
+            Authenticator.Authenticate(Connector);
+
+            return Connector.Send(req);
+        }
+
+        private void OnGetTrainingUsageResponse(RESTConnector.Request req, RESTConnector.Response resp)
+        {
+            DetailedResponse<TrainingEvents> response = new DetailedResponse<TrainingEvents>();
+            foreach (KeyValuePair<string, string> kvp in resp.Headers)
+            {
+                response.Headers.Add(kvp.Key, kvp.Value);
+            }
+            response.StatusCode = resp.HttpResponseCode;
+
+            try
+            {
+                string json = Encoding.UTF8.GetString(resp.Data);
+                response.Result = JsonConvert.DeserializeObject<TrainingEvents>(json);
+                response.Response = json;
+            }
+            catch (Exception e)
+            {
+                Log.Error("VisualRecognitionService.OnGetTrainingUsageResponse()", "Exception: {0}", e.ToString());
+                resp.Success = false;
+            }
+
+            if (((RequestObject<TrainingEvents>)req).Callback != null)
+                ((RequestObject<TrainingEvents>)req).Callback(response, resp.Error);
+        }
+        /// <summary>
         /// Delete labeled data.
         ///
         /// Deletes all data associated with a specified customer ID. The method has no effect if no data is associated