unity sdk
v6.0.0
Используйте этот SDK для создания приложений на базе Watson в Unity.
Начиная с основной версии 6.0.0, API Tone Analyzer был удален в рамках подготовки к прекращению поддержки. Если вы хотите продолжать использовать этот пакет SDK для вызовов Tone Analyzer до его окончательного прекращения поддержки, вам придется использовать предыдущую версию. 24 февраля 2022 года IBM объявила о прекращении поддержки службы Tone Analyzer. Сервис перестанет быть доступен с 24 февраля 2023 г. С 24 февраля 2022 г. вы не сможете создавать новые экземпляры. Существующие экземпляры будут поддерживаться до 24 февраля 2023 г.
В качестве альтернативы мы рекомендуем вам рассмотреть возможность перехода на службу распознавания естественного языка в IBM Cloud. В рамках функции «Понимание естественного языка» анализ тонов выполняется с использованием предварительно созданной модели классификации, которая обеспечивает простой способ обнаружения языковых тонов в письменном тексте. Дополнительные сведения см. в разделе Миграция с конечной точки Watson Tone Analyser Customer Engagement на функцию распознавания естественного языка.
Начиная с основной версии 6.0.0, API NLC был удален в рамках подготовки к прекращению поддержки. Если вы хотите продолжать использовать этот пакет SDK для вызовов NLC до момента его окончательного прекращения поддержки, вам придется использовать предыдущую версию. 9 августа 2021 года IBM объявила о прекращении поддержки службы классификатора естественного языка. Сервис перестанет быть доступен с 8 августа 2022 г. С 9 сентября 2021 г. вы не сможете создавать новые экземпляры. Существующие экземпляры будут поддерживаться до 8 августа 2022 г. Все экземпляры, существующие на эту дату, будут удалены.
В качестве альтернативы мы рекомендуем вам рассмотреть возможность перехода на службу распознавания естественного языка в IBM Cloud, которая использует глубокое обучение для извлечения данных и аналитических данных из текста, таких как ключевые слова, категории, тональность, эмоции и синтаксис, а также расширенный текст с несколькими метками. возможности классификации, чтобы предоставить еще более полную информацию о вашем бизнесе или отрасли. Дополнительные сведения см. в разделе Переход к распознаванию естественного языка.
URL-адреса конечных точек Watson API на сайте watsonplatform.net изменяются и не будут работать после 26 мая 2021 г. Обновите свои вызовы, чтобы использовать новые 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 в каталог Assets вашего проекта Unity. Необязательно: переименуйте каталог SDK из unity-sdk в Watson и каталог Core из unity-sdk-core в IBMSdkCore .
Чтобы создать экземпляры служб Watson и их учетные данные, выполните следующие действия.
Примечание. Учетные данные службы отличаются от имени пользователя и пароля вашей учетной записи IBM Cloud.
Учетные данные для каждой службы содержат либо username , password и url конечной точки , либо apikey и url конечной точки.
ВНИМАНИЕ: вы несете ответственность за безопасность своих учетных данных. Любой пользователь с вашими учетными данными службы может получить доступ к экземплярам вашей службы!
Чтобы начать работу со службой Watson в Unity, перейдите по ссылке, чтобы просмотреть код.
Службы Watson переходят на аутентификацию на основе токенов Identity and Access Management (IAM).
Чтобы узнать, какую аутентификацию использовать, просмотрите учетные данные службы. Учетные данные службы для аутентификации можно найти одинаково для всех служб Watson:
url и либо apikey , либо username и password .В своем коде вы можете использовать эти значения в конструкторе службы или при вызове метода после создания экземпляра службы.
Некоторые службы используют аутентификацию на основе токенов управления идентификацией и доступом (IAM). Аутентификация IAM использует ключ API службы для получения токена доступа, передаваемого вместе с вызовом. Токены доступа действительны в течение примерно одного часа и должны быть восстановлены.
Вы предоставляете либо ключ API службы IAM, либо токен доступа :
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 ) ;
} Вы можете получить заголовки ответов в объекте headers в 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 ) ;
}
} Каждый вызов SDK возвращает ответ с идентификатором транзакции в заголовке X-Global-Transaction-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 по какой-либо причине не возвращает ответ. В этом случае вы можете указать в запросе собственный идентификатор транзакции. Например, замените <my-unique-transaction-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.
Документацию можно найти здесь. Вы также можете получить доступ к документации, выбрав API Reference в меню Watson ( Watson -> API Reference ).
Вы можете просмотреть видеоролики «Начало работы с IBM Watson SDK for Unity» на YouTube.
Если у вас возникли проблемы с API или есть вопросы о службах Watson, см. раздел «Переполнение стека».
Другие проекты с открытым исходным кодом можно найти на странице IBM Github.
Эта библиотека распространяется под лицензией Apache 2.0. Полный текст лицензии доступен в разделе ЛИЦЕНЗИЯ.
См. CONTRIBUTING.md.
Нам бы хотелось выделить крутые проекты с открытым исходным кодом, использующие этот SDK! Если вы хотите, чтобы ваш проект был добавлен в список, не стесняйтесь создать проблему, связывающую нас с ним.
