unity sdk
v6.0.0
使用此 SDK 在 Unity 中建立 Watson 支援的應用程式。
從這個主要版本 6.0.0 開始，音調分析器 API 已被刪除，以準備棄用。如果您希望繼續使用此 sdk 來呼叫 Tone Analyzer，直到其最終棄用，您將必須使用先前的版本。 2022 年 2 月 24 日，IBM 宣布棄用 Tone Analyzer 服務。自 2023 年 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 日起，本服務將不再可用。現有實例將受到支援直至 2022 年 8 月 8 日。
作為替代方案，我們鼓勵您考慮遷移到 IBM Cloud 上的 Natural Language Understanding 服務，該服務使用深度學習從文字中提取資料和見解，例如關鍵字、類別、情緒、情緒和語法以及高級多標籤文字分類功能，為您的企業或產業提供更豐富的見解。有關更多信息，請參閱遷移到自然語言理解。
watsonplatform.net 上的 Watson API 端點 URL 正在更改，並且在 2021 年 5 月 26 日之後將不再運作。有關更多信息，請參閱 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 的超酷開源專案！如果您希望將您的項目添加到清單中，請隨時提出問題將我們連結到該項目。
