unity sdk
v6.0.0
使用此 SDK 在 Unity 中构建 Watson 支持的应用程序。
从这个主要版本 6.0.0 开始，音调分析器 API 已被删除，以准备弃用。如果您希望继续使用此 sdk 来调用 Tone Analyzer，直到其最终弃用，您将必须使用以前的版本。 2022 年 2 月 24 日，IBM 宣布弃用 Tone Analyzer 服务。自 2023 年 2 月 24 日起，该服务将不再可用。自 2022 年 2 月 24 日起，您将无法创建新实例。现有实例的支持截止日期为 2023 年 2 月 24 日。
作为替代方案，我们鼓励您考虑迁移到 IBM Cloud 上的 Natural Language Understanding 服务。通过自然语言理解，语气分析是通过使用预先构建的分类模型来完成的，该模型提供了一种检测书面文本中的语言语气的简单方法。有关更多信息，请参阅从 Watson Tone Analyzer Customer Engagement 端点迁移到 Natural Language Understanding。
从这个主要版本 6.0.0 开始，NLC API 已被删除，以准备弃用。如果您希望继续使用此 sdk 来调用 NLC，直到其最终弃用，您将必须使用以前的版本。 2021 年 8 月 9 日，IBM 宣布弃用自然语言分类器服务。从 2022 年 8 月 8 日起，该服务将不再可用。自 2021 年 9 月 9 日起，您将无法创建新实例。现有实例将受到支持直至 2022 年 8 月 8 日。该日期仍然存在的任何实例都将被删除。
作为替代方案，我们鼓励您考虑迁移到 IBM Cloud 上的 Natural Language Understanding 服务，该服务使用深度学习从文本中提取数据和见解，例如关键字、类别、情感、情感和语法以及高级多标签文本分类功能，为您的企业或行业提供更丰富的见解。有关更多信息，请参阅迁移到自然语言理解。
watsonplatform.net 上的 Watson API 端点 URL 正在更改，并且在 2021 年 5 月 26 日之后将不再工作。请更新您的调用以使用较新的端点 URL。有关更多信息，请参阅 https://cloud.ibm.com/docs/watson?topic=watson-endpoint-change。
确保您具备以下先决条件：
将 MacOS 更新到 Mojave 可能会禁用 Unity 的麦克风。如果您遇到此问题，请参阅这些指南来为 Mojave 配置麦克风。
您可以点击此处获取最新的 SDK 版本。您还需要单击此处下载最新版本的 IBM Unity SDK Core。
将unity-sdk和unity-sdk-core目录移动到 Unity 项目的Assets目录中。可选：将 SDK 目录从unity-sdk重命名为Watson ，将 Core 目录从unity-sdk-core重命名为IBMSdkCore 。
要创建 Watson 服务的实例及其凭证，请按照以下步骤操作。
注：服务凭证与您的 IBM Cloud 帐户用户名和密码不同。
每个服务的凭证包含username 、 password和端点url或apikey和端点url 。
警告：您有责任保护自己的凭据。任何拥有您的服务凭证的用户都可以访问您的服务实例！
要开始在 Unity 中使用 Watson 服务，请点击链接查看代码。
Watson 服务正在迁移到基于令牌的身份和访问管理 (IAM) 身份验证。
要了解要使用的身份验证，请查看服务凭据。对于所有 Watson 服务，您可以使用相同的方式找到用于身份验证的服务凭证：
url以及apikey或username和password 。在代码中，您可以在服务构造函数中使用这些值，或者在实例化服务后通过方法调用使用这些值。
某些服务使用基于令牌的身份和访问管理 (IAM) 身份验证。 IAM 身份验证使用服务 API 密钥来获取随调用传递的访问令牌。访问令牌的有效期约为一小时，必须重新生成。
您提供 IAM 服务API 密钥或访问令牌：
HasIamTokenData()返回true 。 Authenticator authenticator ;
AssistantService assistant ;
string versionDate = "<service-version-date>" ;
IEnumerator TokenExample ( )
{
// Create authenticator using the IAM token options
authenticator = new IamAuthenticator ( apikey : "<iam-api-key>" ) ;
while ( ! authenticator . CanAuthenticate ( ) )
yield return null ;
assistant = new AssistantService ( versionDate , authenticator ) ;
assistant . SetServiceUrl ( "<service-url>" ) ;
assistant . ListWorkspaces ( callback : OnListWorkspaces ) ;
}
private void OnListWorkspaces ( DetailedResponse < WorkspaceCollection > response , IBMError error )
{
Log . Debug ( "OnListWorkspaces()" , "Response: {0}" , response . Response ) ;
} Authenticator authenticator ;
AssistantService assistant ;
string versionDate = "<service-version-date>" ;
void TokenExample ( )
{
// Create authenticator using the Bearer Token
authenticator = new BearerTokenAuthenticator ( "<bearer-token>" ) ;
assistant = new AssistantService ( versionDate , authenticator ) ;
assistant . SetServiceUrl ( "<service-url>" ) ;
assistant . ListWorkspaces ( callback : OnListWorkspaces ) ;
}
private void OnListWorkspaces ( DetailedResponse < WorkspaceCollection > response , IBMError error )
{
Log . Debug ( "OnListWorkspaces()" , "Response: {0}" , response . Response ) ;
} Authenticator authenticator ;
AssistantService assistant ;
string versionDate = "<service-version-date>" ;
void UsernamePasswordExample ( )
{
Authenticator authenticator = new BasicAuthenticator ( "<username>" , "<password>" , "<url>" ) ;
assistant = new AssistantService ( versionDate , authenticator ) ;
assistant . SetServiceUrl ( "<service-url>" ) ;
}有两种方法可以将您在上面找到的身份验证器提供给 SDK 进行身份验证。
使用凭证文件，您只需将文件放在正确的位置，SDK 将完成解析和身份验证的工作。您可以通过单击服务实例的“管理”选项卡中凭证的“下载”按钮来获取此文件。
下载的文件将称为ibm-credentials.env 。这是 SDK 将搜索的名称，除非您想配置文件路径（稍后会详细介绍），否则必须保留该名称。 SDK 将在以下位置（按顺序）查找ibm-credentials.env文件：
只要正确设置，您就不必担心在代码中设置任何身份验证选项。因此，例如，如果您为 Discovery 实例创建并下载了凭证文件，则只需执行以下操作：
public IEnumerator ExampleAutoService ( )
{
Assistant assistantService = new Assistant ( "2019-04-03" ) ;
// Wait for authorization token
while ( ! assistantService . Authenticator . CanAuthenticate ( ) )
yield return null ;
var listWorkspacesResult = assistantService . ListWorkspaces ( ) ;
}就是这样！
如果您在代码中一次使用多个服务并获得两个不同的ibm-credentials.env文件，只需将内容放在一个ibm-credentials.env文件中，SDK 将处理将身份验证器分配给相应的服务。
如果您想配置凭证文件的位置/名称，可以设置一个名为IBM_CREDENTIALS_FILE的环境变量。这将优先于上面指定的位置。您可以按照以下方法执行此操作：
export IBM_CREDENTIALS_FILE= " <path> "其中<path>类似于/home/user/Downloads/<file_name>.env 。
如果您希望在代码中手动设置身份验证值，SDK 也支持该操作。您执行此操作的方式取决于您的服务实例为您提供的身份验证器类型。
需要成功回调。您可以在回调中指定返回类型。
AssistantService assistant ;
string assistantVersionDate = "<assistant-version-date>" ;
Authenticator assistantAuthenticator ;
string workspaceId = "<workspaceId>" ;
DiscoveryService discovery ;
string discoveryVersionDate = "<discovery-version-date>" ;
Authenticator discoveryAuthenticator ;
private void Example ( )
{
assistant = new AssistantService ( assistantVersionDate , assistantAuthenticator ) ;
assistant . SetServiceUrl ( "<service-url>" ) ;
discovery = new DiscoveryService ( discoveryVersionDate , discoveryAuthenticator ) ;
discovery . SetServiceUrl ( "<service-url>" ) ;
// Call with sepcific callbacks
assistant . Message (
callback : OnMessage ,
workspaceId : workspaceId
) ;
discovery . ListEnvironments (
callback : OnGetEnvironments
) ;
}
private void OnMessage ( DetailedResponse < MessageResponse > response , IBMError error )
{
Log . Debug ( "ExampleCallback.OnMessage()" , "Response received: {0}" , response . Response ) ;
}
private void OnGetEnvironments ( DetailedResponse < ListEnvironmentsResponse > response , IBMError error )
{
Log . Debug ( "ExampleCallback.OnGetEnvironments()" , "Response received: {0}" , response . Response ) ;
}由于成功回调签名是通用的，而失败回调始终具有相同的签名，因此您可以使用一组回调来处理多个调用。
AssistantService assistant ;
string assistantVersionDate = "<assistant-version-date>" ;
Authenticator assistantAuthenticator ;
string workspaceId = "<workspaceId>" ;
DiscoveryService discovery ;
string discoveryVersionDate = "<discovery-version-date>" ;
Authenticator discoveryAuthenticator ;
private void Example ( )
{
assistant = new AssistantService ( assistantVersionDate , assistantAuthenticator ) ;
assistant . SetServiceUrl ( "<service-url>" ) ;
// Call with generic callbacks
JObject input = new JObject ( ) ;
input . Add ( "text" , "" ) ;
assistant . Message (
callback : OnSuccess ,
workspaceId : workspaceId ,
input : input
) ;
discovery = new DiscoveryService ( discoveryVersionDate , discoveryAuthenticator ) ;
discovery . SetServiceUrl ( "<service-url>" ) ;
discovery . ListEnvironments (
callback : OnSuccess
) ;
}
// Generic success callback
private void OnSuccess < T > ( DetailedResponse < T > resp , IBMError error )
{
Log . Debug ( "ExampleCallback.OnSuccess()" , "Response received: {0}" , resp . Response ) ;
}您还可以使用匿名回调
AssistantService assistant ;
string assistantVersionDate = "<assistant-version-date>" ;
Authenticator assistantAuthenticator ;
string workspaceId = "<workspaceId>" ;
private void Example ( )
{
assistant = new AssistantService ( assistantVersionDate , assistantAuthenticator ) ;
assistant . ListWorkspaces (
callback : ( DetailedResponse < WorkspaceCollection > response , IBMError error ) =>
{
Log . Debug ( "ExampleCallback.OnSuccess()" , "ListWorkspaces result: {0}" , response . Response ) ;
} ,
pageLimit : 1 ,
includeCount : true ,
sort : "-name" ,
includeAudit : true
) ;
assistant . SetServiceUrl ( "<service-url>" ) ;
}您可以检查error响应以查看调用中是否存在错误。
AssistantService assistant ;
string assistantVersionDate = "<assistant-version-date>" ;
Authenticator assistantAuthenticator ;
string workspaceId = "<workspaceId>" ;
private void Example ( )
{
assistant = new AssistantService ( versionDate , authenticator ) ;
assistant . Message ( OnMessage , workspaceId ) ;
}
private void OnMessage ( DetailedResponse < MessageResponse > response , IBMError error )
{
if ( error == null )
{
Log . Debug ( "ExampleCallback.OnMessage()" , "Response received: {0}" , response . Response ) ;
}
else
{
Log . Debug ( "ExampleCallback.OnMessage()" , "Error received: {0}, {1}, {3}" , error . StatusCode , error . ErrorMessage , error . Response ) ;
}
} 您可以通过将自定义请求标头添加到服务来发送它们。
AssistantService assistant ;
string assistantVersionDate = "<assistant-version-date>" ;
Authenticator assistantAuthenticator ;
string workspaceId = "<workspaceId>" ;
void Example ( )
{
assistant = new AssistantService ( assistantVersionDate , assistantAuthenticator ) ;
// Add custom header to the REST call
assistant . WithHeader ( "X-Watson-Metadata" , "customer_id=some-assistant-customer-id" ) ;
assistant . Message ( OnSuccess , "<workspace-id>" ) ;
}
private void OnSuccess ( DetailedResponse < MessageResponse > response , IBMError error )
{
Log . Debug ( "ExampleCallback.OnMessage()" , "Response received: {0}" , response . Response ) ;
} 您可以在DetailedResponse 的headers对象中获取响应标头。
AssistantService assistant ;
string assistantVersionDate = "<assistant-version-date>" ;
Authenticator assistantAuthenticator ;
string workspaceId = "<workspaceId>" ;
void Example ( )
{
assistant = new AssistantService ( assistantVersionDate , assistantAuthenticator ) ;
assistant . Message ( OnMessage , "<workspace-id>" ) ;
}
private void OnMessage ( DetailedResponse < MessageResponse > response , IBMError error )
{
// List all headers in the response headers object
foreach ( KeyValuePair < string , object > kvp in response . Headers )
{
Log . Debug ( "ExampleCustomHeader.OnMessage()" , "{0}: {1}" , kvp . Key , kvp . Value ) ;
}
} 每个 SDK 调用都会返回一个响应，其中X-Global-Transaction-Id标头中包含事务 ID。该 ID 与服务实例区域一起帮助支持团队从相关日志中解决问题。
public void ExampleGetTransactionId ( )
{
AssistantService service = new AssistantService ( "{version-date}" ) ;
service . ListWorkspaces (
callback : ( DetailedResponse < Workspace > response , IBMError error ) =>
{
if ( error != null )
{
Log . Debug ( "AssistantServiceV1" , "Transaction Id: {0}" , error . ResponseHeaders [ "X-Global-Transaction-Id" ] ) ;
}
else
{
Log . Debug ( "AssistantServiceV1" , "Transaction Id: {0}" , response . Headers [ "X-Global-Transaction-Id" ] ) ;
}
}
) ;
}但是，当 API 由于某种原因未返回响应时，交易 ID 不可用。在这种情况下，您可以在请求中设置自己的事务 ID。例如，将以下示例中的<my-unique-transaction-id>替换为唯一事务 ID。
public void ExampleSetTransactionId ( )
{
AssistantService service = new AssistantService ( "{version-date}" ) ;
service . WithHeader ( "X-Global-Transaction-Id" , "<my-unique-transaction-id>" ) ;
service . ListWorkspaces (
callback : ( DetailedResponse < Workspace > response , IBMError error ) =>
{
if ( error != null )
{
Log . Debug ( "AssistantServiceV1" , "Transaction Id: {0}" , error . ResponseHeaders [ "X-Global-Transaction-Id" ] ) ;
}
else
{
Log . Debug ( "AssistantServiceV1" , "Transaction Id: {0}" , response . Headers [ "X-Global-Transaction-Id" ] ) ;
}
}
) ;
} Watson 服务已将其主机升级到 TLS 1.2。达拉斯位置有一个适用于流式传输的 TLS 1.0 端点。要在其他区域进行流式传输，请使用 Unity 2018.2 并将“构建设置”中的“脚本运行时版本”设置为.NET 4.x equivalent 。要在早期版本的 Unity 中支持语音转文本，请在达拉斯位置创建实例。
您可以在进行服务调用时禁用 SSL 验证。
AssistantService assistant ;
string assistantVersionDate = "<assistant-version-date>" ;
Authenticator assistantAuthenticator ;
string workspaceId = "<workspaceId>" ;
void Example ( )
{
authenticator . DisableSslVerification = true ;
assistant = new AssistantService ( assistantVersionDate , assistantAuthenticator ) ;
// disable ssl verification
assistant . DisableSslVerification = true ;
} 如果您的服务实例是ICP4D，下面有两种初始化辅助服务的方法。
username 、 password 、 icp4d_url和authentication_typeSDK将为用户管理令牌
CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator ( "<url>" , "<username>" , "<password>" ) ;
while ( ! authenticator . CanAuthenticate ( ) )
{
yield return null ;
}
service = new AssistantService ( versionDate , authenticator ) ; BearerTokenAuthenticator = new BearerTokenAuthenticator ( "<accessToken>" ) ;
while ( ! authenticator . CanAuthenticate ( ) )
{
yield return null ;
}
service = new AssistantService ( versionDate , authenticator ) ; Watson Unity SDK 不支持 IBM Cloud Private，因为 UnityWebRequest 不支持通过代理进行连接。
可以在此处找到文档。您还可以通过选择 Watson 菜单中的 API Reference（ Watson -> API Reference ）来访问文档。
您可以在 YouTube 上观看 IBM Watson SDK for Unity 的入门视频。
如果您对 API 有问题或对 Watson 服务有疑问，请参阅 Stack Overflow。
在 IBM Github 页面上查找更多开源项目。
该库已获得 Apache 2.0 许可。完整的许可证文本可在许可证中找到。
请参阅 CONTRIBUTING.md。
我们很乐意重点介绍使用此 SDK 的超酷开源项目！如果您希望将您的项目添加到列表中，请随时提出问题将我们链接到该项目。
