Merge pull request #540 from watson-developer-cloud/feature-v3-datetime

DateTime formatting

Author: mediumTaj

Core

@@ -32,13 +32,14 @@ Ensure that you have the following prerequisites:
 
 ## Configuring Unity
 * Change the build settings in Unity (**File > Build Settings**) to any platform except for web player/Web GL. The IBM Watson SDK for Unity does not support Unity Web Player.
-* If using Unity 2018.2 or later you'll need to set Scripting Runtime Version in Build Settings to .NET 4.x equivalent. We need to access security options to enable TLS 1.2. 
+* If using Unity 2018.2 or later you'll need to set Scripting Runtime Version and Api Compatibility Level in Build Settings to .NET 4.x equivalent. We need to access security options to enable TLS 1.2. 
 
 ## Getting the Watson SDK and adding it to Unity
 You can get the latest SDK release by clicking [here][latest_release].
 
 ### Installing the SDK source into your Unity project
-Move the **`unity-sdk`** directory into the **`Assets`** directory of your Unity project. _Optional: rename the SDK directory from `unity-sdk` to `Watson`_.
+1. Move the **`unity-sdk`** directory into the **`Assets`** directory of your Unity project. _Optional: rename the SDK directory from `unity-sdk` to `Watson`_.
+2. Using the command line, from the sdk directory run `git submodule init` and `git submodule update` to get the correct commit of the SDK core.
 
 ## Configuring your service credentials
 To create instances of Watson services and their credentials, follow the steps below.
@@ -124,17 +125,12 @@ IEnumerator TokenExample()
 
     _assistant = new Assistant(_credentials);
     _assistant.VersionDate = "2018-02-16";
-    _assistant.ListWorkspaces(OnListWorkspaces, OnFail);
+    _assistant.ListWorkspaces(OnListWorkspaces);
 }
 
-private void OnListWorkspaces(WorkspaceCollection response, Dictionary<string, object> customData)
+private void OnListWorkspaces(DetailedResponse<WorkspaceCollection> response, IBMError error)
 {
-    Log.Debug("OnListWorkspaces()", "Response: {0}", customData["json"].ToString());
-}
-
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Debug("OnFail()", "Failed: {0}", error.ToString());
+    Log.Debug("OnListWorkspaces()", "Response: {0}", response.Response);
 }
 ```
 
@@ -153,24 +149,19 @@ void TokenExample()
 
     _assistant = new Assistant(_credentials);
     _assistant.VersionDate = "2018-02-16";
-    _assistant.ListWorkspaces(OnListWorkspaces, OnFail);
+    _assistant.ListWorkspaces(OnListWorkspaces);
 }
 
-private void OnListWorkspaces(WorkspaceCollection response, Dictionary<string, object> customData)
+private void OnListWorkspaces(DetailedResponse<WorkspaceCollection> response, IBMError error)
 {
-    Log.Debug("OnListWorkspaces()", "Response: {0}", customData["json"].ToString());
-}
-
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Debug("OnFail()", "Failed: {0}", error.ToString());
+    Log.Debug("OnListWorkspaces()", "Response: {0}", response.Response);
 }
 ```
 
 ### Username and password
 ```cs
-using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
-using IBM.Watson.DeveloperCloud.Utilities;
+using IBM.Watson.Assistant.v1;
+using IBM.Cloud.SDK.Utilities;
 
 void Start()
 {
@@ -180,37 +171,25 @@ void Start()
 ```
 
 ## Callbacks
-Success and failure callbacks are required. You can specify the return type in the callback.  
+Success callbacks are required. You can specify the return type in the callback.  
 ```cs
 private void Example()
 {
     //  Call with sepcific callbacks
-    assistant.Message(OnMessage, OnGetEnvironmentsFail, _workspaceId, "");
-    discovery.GetEnvironments(OnGetEnvironments, OnFail);
+    assistant.Message(OnMessage, _workspaceId);
+    discovery.GetEnvironments(OnGetEnvironments);
 }
 
 //  OnMessage callback
-private void OnMessage(object resp, Dictionary<string, object> customData)
+private void OnMessage(DetailedResponse<JObject> resp, IBMError error)
 {
-    Log.Debug("ExampleCallback.OnMessage()", "Response received: {0}", customData["json"].ToString());
+    Log.Debug("ExampleCallback.OnMessage()", "Response received: {0}", resp.Response);
 }
 
 //  OnGetEnvironments callback
-private void OnGetEnvironments(GetEnvironmentsResponse resp, Dictionary<string, object> customData)
-{
-    Log.Debug("ExampleCallback.OnGetEnvironments()", "Response received: {0}", customData["json"].ToString());
-}
-
-//  OnMessageFail callback
-private void OnMessageFail(RESTConnector.Error error, Dictionary<string, object> customData)
+private void OnGetEnvironments(DetailedResponse<GetEnvironmentsResponse> resp, IBMError error)
 {
-    Log.Error("ExampleCallback.OnMessageFail()", "Error received: {0}", error.ToString());
-}
-
-//  OnGetEnvironmentsFail callback
-private void OnGetEnvironmentsFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Error("ExampleCallback.OnGetEnvironmentsFail()", "Error received: {0}", error.ToString());
+    Log.Debug("ExampleCallback.OnGetEnvironments()", "Response received: {0}", resp.Response);
 }
 ```
 
@@ -219,131 +198,47 @@ Since the success callback signature is generic and the failure callback always
 private void Example()
 {
     //  Call with generic callbacks
-    assistant.Message(OnSuccess, OnMessageFail, "<workspace-id>", "");
-    discovery.GetEnvironments(OnSuccess, OnFail);
+    assistant.Message(OnSuccess, "<workspace-id>", "");
+    discovery.GetEnvironments(OnSuccess);
 }
 
 //  Generic success callback
-private void OnSuccess<T>(T resp, Dictionary<string, object> customData)
-{
-    Log.Debug("ExampleCallback.OnSuccess()", "Response received: {0}", customData["json"].ToString());
-}
-
-//  Generic fail callback
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
+private void OnSuccess<T>(DetailedResponse<T> resp, IBMError error)
 {
-    Log.Error("ExampleCallback.OnFail()", "Error received: {0}", error.ToString());
-}
-```
-
-## Custom data
-Custom data can be passed through a `Dictionary<string, object> customData` in each call. In most cases, the raw json response is returned in the customData under `"json"` entry. In cases where there is no returned json, the entry will contain the success and http response code of the call.
-
-```cs
-void Example()
-{
-    Dictionary<string, object> customData = new Dictionary<string, object>();
-    customData.Add("foo", "bar");
-    assistant.Message(OnSuccess, OnFail, "<workspace-id>", "", customData);
-}
-
-//  Generic success callback
-private void OnSuccess<T>(T resp, Dictionary<string, object> customData)
-{
-    Log.Debug("ExampleCustomData.OnSuccess()", "Custom Data: {0}", customData["foo"].ToString());  // returns "bar"
-}
-
-//  Generic fail callback
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Error("ExampleCustomData.OnFail()", "Error received: {0}", error.ToString());  // returns error string
-    Log.Debug("ExampleCustomData.OnFail()", "Custom Data: {0}", customData["foo"].ToString());  // returns "bar"
+    Log.Debug("ExampleCallback.OnSuccess()", "Response received: {0}", resp.Response);
 }
 ```
 
 ## Custom Request Headers
-You can send custom request headers by adding them to the `customData` object.
+You can send custom request headers by adding them to the service.
 
 ```cs
 void Example()
 {
-    //  Create customData object
-    Dictionary<string, object> customData = new Dictionary<string, object>();
-    //  Create a dictionary of custom headers
-    Dictionary<string, string> customHeaders = new Dictionary<string, string>();
-    //  Add to the header dictionary
-    customHeaders.Add("X-Watson-Metadata", "customer_id=some-assistant-customer-id");
-    //  Add the header dictionary to the custom data object
-    customData.Add(Constants.String.CUSTOM_REQUEST_HEADERS, customHeaders);
-
-    assistant.Message(OnSuccess, OnFail, "<workspace-id>", customData: customData);
+    assistant.AddHeader("X-Watson-Metadata", "customer_id=some-assistant-customer-id");
+    assistant.Message(OnSuccess, "<workspace-id>");
 }
 ```
 
 ## Response Headers
-You can get responseheaders in the `customData` object in the callback.
+You can get response headers in the `headers` object in the DetailedResponse.
 
 ```cs
 void Example()
 {
-    assistant.Message(OnMessage, OnFail, "<workspace-id>");
+    assistant.Message(OnMessage, "<workspace-id>");
 }
 
-private void OnMessage(object resp, Dictionary<string, object> customData)
+private void OnMessage(DetailedResponse<JOBject> resp, IBMError error)
 {
     //  List all headers in the response headers object
-    if (customData.ContainsKey(Constants.String.RESPONSE_HEADERS))
+    foreach (KeyValuePair<string, string> kvp in resp.Headers)
     {
-        foreach (KeyValuePair<string, string> kvp in customData[Constants.String.RESPONSE_HEADERS] as Dictionary<string, string>)
-        {
-            Log.Debug("ExampleCustomHeader.OnMessage()", "{0}: {1}", kvp.Key, kvp.Value);
-        }
+        Log.Debug("ExampleCustomHeader.OnMessage()", "{0}: {1}", kvp.Key, kvp.Value);
     }
 }
 ```
 
-## Authentication Tokens
-
-**Authenticating with the `X-Watson-Authorization-Token` header is deprecated. The token continues to work with Cloud Foundry services, but is not supported for services that use Identity and Access Management (IAM) authentication. For details see [Authenticating with IAM tokens](https://console.bluemix.net/docs/services/watson/getting-started-iam.html#iam) or the [README](#IAM) in the IBM Watson SDK you use.**
-
-You use tokens to write applications that make authenticated requests to IBM Watson™ services without embedding service credentials in every call.
-
-You can write an authentication proxy in IBM Cloud that obtains and returns a token to your client application, which can then use the token to call the service directly. This proxy eliminates the need to channel all service requests through an intermediate server-side application, which is otherwise necessary to avoid exposing your service credentials from your client application.
-
-```cs
-using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-void Start()
-{
-    Credentials credentials = new Credentials(<service-url>)
-    {
-        AuthenticationToken = <authentication-token>
-    };
-    Assistant _assistant = new Assistant(credentials);
-}
-```
-
-There is a helper class included to obtain tokens from within your Unity application.
-
-```cs
-using IBM.Watson.DeveloperCloud.Utilities;
-
-AuthenticationToken _authenticationToken;
-
-void Start()
-{
-    if (!Utility.GetToken(OnGetToken, <service-url>, <service-username>, <service-password>))
-        Log.Debug("ExampleGetToken.Start()", "Failed to get token.");
-}
-
-private void OnGetToken(AuthenticationToken authenticationToken, string customData)
-{
-    _authenticationToken = authenticationToken;
-    Log.Debug("ExampleGetToken.OnGetToken()", "created: {0} | time to expiration: {1} minutes | token: {2}", _authenticationToken.Created, _authenticationToken.TimeUntilExpiration, _authenticationToken.Token);
-}
-```
-
 ## Streaming outside of US South region
 Watson services have upgraded their hosts to TLS 1.2. The US South region has a TLS 1.0 endpoint that will work for streaming but if you are streaming in other regions you will need to use Unity 2018.2 and set Scripting Runtime Version in Build Settings to .NET 4.x equivalent. In lower versions of Unity you will need to create the Speech to Text instance in US South.
 
@@ -366,7 +261,7 @@ The Watson Unity SDK does not support IBM Cloud Private because connection via p
 Documentation can be found [here][documentation]. You can also access the documentation by selecting API Reference the Watson menu (**Watson -> API Reference**).
 
 ## Getting started videos
-You can view Getting Started videos for the IBM Watson SDK for Unity on [YouTube](https://www.youtube.com/watch?v=Sa5hmukwHV8&list=PLZDyxLlNKRY8MdgiUq45cZztn_f0EVz6c).
+You can view Getting Started videos for the IBM Watson SDK for Unity on [YouTube](https://www.youtube.com/watch?v=sNPsdUWSi34&list=PLZDyxLlNKRY9b2vurEhkSoNWZN5c5l4Nr).
 
 ## Questions
 

README.md

@@ -30,7 +30,7 @@ namespace IBM.Watson.Assistant.V1
 {
     public partial class AssistantService : BaseService
     {
-        private const string serviceId = "conversation";
+        private const string serviceId = "assistant";
         private const string defaultUrl = "https://gateway.watsonplatform.net/assistant/api";
 
         #region Credentials

Scripts/Services/Assistant/V1/AssistantService.cs

@@ -30,7 +30,7 @@ namespace IBM.Watson.Assistant.V2
 {
     public partial class AssistantService : BaseService
     {
-        private const string serviceId = "conversation";
+        private const string serviceId = "assistant";
         private const string defaultUrl = "https://gateway.watsonplatform.net/assistant/api";
 
         #region Credentials

Scripts/Services/Assistant/V2/AssistantService.cs

@@ -30,7 +30,7 @@ namespace IBM.Watson.CompareComply.V1
 {
     public partial class CompareComplyService : BaseService
     {
-        private const string serviceId = "compare-comply";
+        private const string serviceId = "compare_comply";
         private const string defaultUrl = "https://gateway.watsonplatform.net/compare-comply/api";
 
         #region Credentials

Scripts/Services/CompareComply/V1/CompareComplyService.cs

@@ -30,7 +30,7 @@ namespace IBM.Watson.NaturalLanguageUnderstanding.V1
 {
     public partial class NaturalLanguageUnderstandingService : BaseService
     {
-        private const string serviceId = "natural-language-understanding";
+        private const string serviceId = "natural_language_understanding";
         private const string defaultUrl = "https://gateway.watsonplatform.net/natural-language-understanding/api";
 
         #region Credentials

Scripts/Services/NaturalLanguageUnderstanding/V1/NaturalLanguageUnderstandingService.cs

@@ -4030,11 +4030,17 @@ private void OnUpgradeAcousticModelResponse(RESTConnector.Request req, RESTConne
         /// * `application/zip` for a **.zip** file
         /// * `application/gzip` for a **.tar.gz** file.
         ///
-        /// All audio files contained in the archive must have the same audio format. Use the `Contained-Content-Type`
-        /// parameter to specify the format of the contained audio files. The parameter accepts all of the audio formats
-        /// supported for use with speech recognition and with the `Content-Type` header, including the `rate`,
-        /// `channels`, and `endianness` parameters that are used with some formats. The default contained audio format
-        /// is `audio/wav`.
+        /// When you add an archive-type resource, the `Contained-Content-Type` header is optional depending on the
+        /// format of the files that you are adding:
+        /// * For audio files of type `audio/alaw`, `audio/basic`, `audio/l16`, or `audio/mulaw`, you must use the
+        /// `Contained-Content-Type` header to specify the format of the contained audio files. Include the `rate`,
+        /// `channels`, and `endianness` parameters where necessary. In this case, all audio files contained in the
+        /// archive file must have the same audio format.
+        /// * For audio files of all other types, you can omit the `Contained-Content-Type` header. In this case, the
+        /// audio files contained in the archive file can have any of the formats not listed in the previous bullet. The
+        /// audio files do not need to have the same format.
+        ///
+        /// Do not use the `Contained-Content-Type` header when adding an audio-type resource.
         ///
         /// ### Naming restrictions for embedded audio files
         ///
@@ -4056,11 +4062,18 @@ private void OnUpgradeAcousticModelResponse(RESTConnector.Request req, RESTConne
         /// * Do not use the name of an audio resource that has already been added to the custom model.</param>
         /// <param name="audioResource">The audio resource that is to be added to the custom acoustic model, an
         /// individual audio file or an archive file.</param>
-        /// <param name="containedContentType">For an archive-type resource, specifies the format of the audio files
-        /// that are contained in the archive file. The parameter accepts all of the audio formats that are supported
-        /// for use with speech recognition, including the `rate`, `channels`, and `endianness` parameters that are used
-        /// with some formats. For more information, see **Content types for audio-type resources** in the method
-        /// description. (optional, default to audio/wav)</param>
+        /// <param name="containedContentType">**For an archive-type resource,** specify the format of the audio files
+        /// that are contained in the archive file if they are of type `audio/alaw`, `audio/basic`, `audio/l16`, or
+        /// `audio/mulaw`. Include the `rate`, `channels`, and `endianness` parameters where necessary. In this case,
+        /// all audio files that are contained in the archive file must be of the indicated type.
+        ///
+        /// For all other audio formats, you can omit the header. In this case, the audio files can be of multiple types
+        /// as long as they are not of the types listed in the previous paragraph.
+        ///
+        /// The parameter accepts all of the audio formats that are supported for use with speech recognition. For more
+        /// information, see **Content types for audio-type resources** in the method description.
+        ///
+        /// **For an audio-type resource,** omit the header. (optional)</param>
         /// <param name="allowOverwrite">If `true`, the specified audio resource overwrites an existing audio resource
         /// with the same name. If `false`, the request fails if an audio resource with the same name already exists.
         /// The parameter has no effect if an audio resource with the same name does not already exist. (optional,

Scripts/Services/SpeechToText/V1/SpeechToTextService.cs

@@ -270,8 +270,9 @@ private void OnListVoicesResponse(RESTConnector.Request req, RESTConnector.Respo
         /// language for the input text on the specified voice. Use a voice that matches the language of the input text.
         ///
         ///
-        /// The service returns the synthesized audio stream as an array of bytes. You can pass a maximum of 5 KB of
-        /// text to the service.
+        /// The method accepts a maximum of 5 KB of input text in the body of the request, and 8 KB for the URL and
+        /// headers. The 5 KB limit includes any SSML tags that you specify. The service returns the synthesized audio
+        /// stream as an array of bytes.
         ///
         /// **See also:** [The HTTP interface](https://cloud.ibm.com/docs/services/text-to-speech/http.html).
         ///