unity sdk
v6.0.0
Use este SDK para criar aplicativos com tecnologia Watson no Unity.
A partir desta versão principal, 6.0.0, a API Tone Analyzer foi removida em preparação para a descontinuação. Se você deseja continuar usando este SDK para fazer chamadas ao Tone Analyzer até sua descontinuação final, você terá que usar uma versão anterior. Em 24 de fevereiro de 2022, a IBM anunciou a descontinuação do serviço Tone Analyzer. O serviço não estará mais disponível a partir de 24 de fevereiro de 2023. A partir de 24 de fevereiro de 2022, você não poderá criar novas instâncias. As instâncias existentes terão suporte até 24 de fevereiro de 2023.
Como alternativa, encorajamos você a considerar a migração para o serviço Natural Language Understanding na IBM Cloud. Com o Natural Language Understanding, a análise de tons é feita usando um modelo de classificação pré-construído, que fornece uma maneira fácil de detectar tons de linguagem em texto escrito. Para obter mais informações, consulte Migrando do terminal do Watson Tone Analyzer Customer Engagement para o Natural Language Understanding.
A partir desta versão principal, 6.0.0, a API NLC foi removida em preparação para a descontinuação. Se desejar continuar usando este SDK para fazer chamadas ao NLC até sua descontinuação final, você terá que usar uma versão anterior. Em 9 de agosto de 2021, a IBM anunciou a descontinuação do serviço Natural Language Classifier. O serviço não estará mais disponível a partir de 8 de agosto de 2022. A partir de 9 de setembro de 2021, você não poderá criar novas instâncias. As instâncias existentes terão suporte até 8 de agosto de 2022. Qualquer instância que ainda existir nessa data será excluída.
Como alternativa, incentivamos você a considerar a migração para o serviço Natural Language Understanding na IBM Cloud, que usa aprendizagem profunda para extrair dados e insights de texto, como palavras-chave, categorias, sentimento, emoção e sintaxe, juntamente com texto avançado com vários rótulos. recursos de classificação, para fornecer insights ainda mais ricos para seu negócio ou setor. Para obter mais informações, consulte Migrando para o Natural Language Understanding.
Os URLs de terminal da API Watson em watsonplatform.net estão mudando e não funcionarão após 26 de maio de 2021. Atualize suas chamadas para usar os URLs de terminal mais recentes. Para obter informações adicionais, consulte https://cloud.ibm.com/docs/watson?topic=watson-endpoint-change.
Certifique-se de ter os seguintes pré-requisitos:
Atualizar o MacOS para o Mojave pode desativar o microfone do Unity. Se você estiver enfrentando esse problema, consulte estas diretrizes para configurar o microfone para Mojave.
Você pode obter a versão mais recente do SDK clicando aqui. Você também precisará fazer download da versão mais recente do IBM Unity SDK Core clicando aqui.
Mova os diretórios unity-sdk e unity-sdk-core para o diretório Assets do seu projeto Unity. Opcional: renomeie o diretório SDK de unity-sdk para Watson e o diretório Core de unity-sdk-core para IBMSdkCore .
Para criar instâncias de serviços Watson e suas credenciais, siga as etapas abaixo.
Nota: As credenciais de serviço são diferentes do nome de usuário e da senha da sua conta IBM Cloud.
As credenciais para cada serviço contêm um username , password e url de endpoint ou uma apikey e um url de endpoint.
AVISO: Você é responsável por proteger suas próprias credenciais. Qualquer usuário com suas credenciais de serviço pode acessar suas instâncias de serviço!
Para começar a usar um serviço Watson no Unity, siga o link para ver o código.
Os serviços Watson estão migrando para a autenticação de gerenciamento de identidade e acesso (IAM) baseada em token.
Para descobrir qual autenticação usar, visualize as credenciais do serviço. Você encontra as credenciais de serviço para autenticação da mesma maneira para todos os serviços Watson:
url e apikey ou username e password .No seu código, você pode usar esses valores no construtor de serviço ou com uma chamada de método após instanciar seu serviço.
Alguns serviços usam autenticação de gerenciamento de identidade e acesso (IAM) baseada em token. A autenticação IAM usa uma chave de API de serviço para obter um token de acesso que é transmitido com a chamada. Os tokens de acesso são válidos por aproximadamente uma hora e devem ser regenerados.
Você fornece uma chave de API de serviço IAM ou um token de acesso :
HasIamTokenData() retorne 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>" ) ;
}Existem duas maneiras de fornecer o autenticador encontrado acima ao SDK para autenticação.
Com um arquivo de credencial, você só precisa colocar o arquivo no lugar certo e o SDK fará o trabalho de analisá-lo e autenticá-lo. Você pode obter esse arquivo clicando no botão Download das credenciais na guia Gerenciar da sua instância de serviço.
O arquivo transferido por download será denominado ibm-credentials.env . Este é o nome que o SDK irá procurar e deve ser preservado, a menos que você queira configurar o caminho do arquivo (mais sobre isso mais tarde). O SDK procurará seu arquivo ibm-credentials.env nos seguintes locais (em ordem):
Contanto que você configure isso corretamente, você não precisa se preocupar em definir nenhuma opção de autenticação em seu código. Assim, por exemplo, se você criou e baixou o arquivo de credenciais para sua instância do Discovery, basta fazer o seguinte:
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 ( ) ;
}E é isso!
Se você estiver usando mais de um serviço por vez em seu código e obtiver dois arquivos ibm-credentials.env diferentes, basta reunir o conteúdo em um arquivo ibm-credentials.env e o SDK tratará da atribuição do autenticador aos serviços apropriados .
Se desejar configurar o local/nome do seu arquivo de credenciais, você poderá configurar uma variável de ambiente chamada IBM_CREDENTIALS_FILE . Isto terá precedência sobre os locais especificados acima. Veja como você pode fazer isso:
export IBM_CREDENTIALS_FILE= " <path> " onde <path> é algo como /home/user/Downloads/<file_name>.env .
Se você preferir definir valores de autenticação manualmente em seu código, o SDK também oferece suporte para isso. A maneira como você fará isso depende do tipo de autenticador que sua instância de serviço oferece.
Um retorno de chamada bem-sucedido é necessário. Você pode especificar o tipo de retorno no retorno de chamada.
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 ) ;
}Como a assinatura do retorno de chamada de sucesso é genérica e o retorno de chamada de falha sempre tem a mesma assinatura, você pode usar um único conjunto de retornos de chamada para lidar com diversas chamadas.
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 ) ;
}Você também pode usar um retorno de chamada anônimo
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>" ) ;
} Você pode verificar a resposta error para ver se houve algum erro na chamada.
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 ) ;
}
} Você pode enviar cabeçalhos de solicitação personalizados adicionando-os ao serviço.
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 ) ;
} Você pode obter cabeçalhos de resposta no objeto headers em DetailedResponse.
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 ) ;
}
} Cada chamada do SDK retorna uma resposta com um ID de transação no cabeçalho X-Global-Transaction-Id . Juntamente com a região da instância de serviço, esse ID ajuda as equipes de suporte a solucionar problemas de logs relevantes.
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" ] ) ;
}
}
) ;
} No entanto, o ID da transação não está disponível quando a API não retorna uma resposta por algum motivo. Nesse caso, você pode definir seu próprio ID de transação na solicitação. Por exemplo, substitua <my-unique-transaction-id> no exemplo a seguir por um ID de transação exclusivo.
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" ] ) ;
}
}
) ;
} Os serviços Watson atualizaram seus hosts para o TLS 1.2. O local de Dallas possui um endpoint TLS 1.0 que funciona para streaming. Para transmitir em outras regiões, use o Unity 2018.2 e defina a versão do Scripting Runtime nas configurações de compilação como .NET 4.x equivalent Para oferecer suporte ao Speech to Text em versões anteriores do Unity, crie a instância no local de Dallas.
Você pode desativar a verificação SSL ao fazer uma chamada de serviço.
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 ;
} Se sua instância de serviço for ICP4D, abaixo estão duas maneiras de inicializar o serviço assistente.
username , password , icp4d_url e authentication_typeO SDK gerenciará o token para o usuário
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 ) ; O Watson Unity SDK não suporta o IBM Cloud Private porque a conexão via proxy não é suportada no UnityWebRequest.
A documentação pode ser encontrada aqui. Você também pode acessar a documentação selecionando API Reference no menu Watson ( Watson -> API Reference ).
É possível visualizar vídeos de introdução ao IBM Watson SDK for Unity no YouTube.
Se você tiver problemas com as APIs ou tiver alguma dúvida sobre os serviços do Watson, consulte Stack Overflow.
Encontre mais projetos de código aberto na página IBM Github.
Esta biblioteca está licenciada sob Apache 2.0. O texto completo da licença está disponível em LICENSE.
Consulte CONTRIBUTING.md.
Adoraríamos destacar projetos interessantes de código aberto que usam este SDK! Se desejar que seu projeto seja adicionado à lista, sinta-se à vontade para criar um problema vinculando-nos a ele.
