Watson 开发者云 Swift SDK

已弃用的构建

概述

Watson 开发者云 Swift SDK 让移动开发者轻松构建 Watson 动力的应用程序。使用 Swift SDK，您可以利用 Watson 先进的智能、机器学习和深度学习技术来理解非结构化数据并以新颖的方式与移动用户互动。

有许多资源可以帮助您使用 Swift SDK 构建 cognitive 应用程序

查看特色项目
浏览文档

服务

此 SDK 提供了访问以下 Watson 服务的类和方法。

公告

语调分析器弃用

从本重大版本5.0.0开始，为了弃用准备，已移除Tone Analyzer API。如果您希望继续使用此sdk调用Tone Analyzer，直到最终弃用，您将不得不使用旧版。

2022年2月24日，IBM宣布弃用Tone Analyzer服务。该服务将从2023年2月24日起不再可用。自2022年2月24日起，您将无法创建新实例。现有实例将得到支持，直至2023年2月24日。

作为替代方案，我们鼓励您考虑将应用迁移到IBM Cloud上的自然语言理解服务。使用自然语言理解，可以使用预建的分类模型进行语调分析，这为检测书面文本中的语调提供了一种简单方法。更多详细信息，请参阅从Watson Tone Analyzer Customer Engagement端点迁移到自然语言理解。

自然语言分类器弃用

从本重大版本5.0.0开始，为弃用做准备，已移除NLC API。如果您希望继续使用此sdk调用NLC，直到最终弃用，您将不得不使用旧版。

2021年8月9日，IBM宣布弃用自然语言分类器服务。服务将从2022年8月8日起不再可用。自2021年9月9日起，您将无法创建新实例。现有实例将得到支持，直至2022年8月8日。任何在该日期仍然存在的实例将被删除。

作为替代方案，我们鼓励您考虑将应用迁移到IBM Cloud的自然语言理解服务，该服务使用深度学习从文本中提取数据和分析，例如关键词、类别、情感、句法和语义，并具有高级多标签文本分类功能，为您的业务或行业提供更加丰富的见解。更多详细信息，请参阅迁移到自然语言理解。

在开始之前

您需要一个IBM Cloud账户。

要求

Xcode 10.2+
Swift 5.0+
iOS 10.0+

安装

IBM Watson Swift SDK可以通过Swift Package Manager、Cocoapods或Carthage进行安装。

Swift包管理器

从版本4.0.2开始，Watson开发者云Swift SDK现在通过Swift包管理器支持所有服务。

在屏幕顶部的XCode菜单栏中点击文件 -> Swift包 -> 添加包依赖项，根据提示粘贴github url https://github.com/watson-developer-cloud/swift-sdk和适当的使用最新的主要版本。请确保只选择您计划要使用的服务，否则您可能会遇到长的构建时间

要将服务导入到您的项目

import AssistantV2
import DiscoveryV2
.
.
.

(只有语音转文本和文本到语音) 这些服务使用libogg和opus库，在安装包之前需要采取额外步骤。

您需要安装Homebrew
安装libogg和opus
```
$ brew install libogg opus
```
根据当前库版本，必须删除打包的动态库。

当前libogg版本：1.3.4。

当前opus版本：1.3.1
```
$ rm -f /usr/local/Cellar/libogg/1.3.4/lib/*.dylib
```
```
$ rm -f /usr/local/Cellar/opus/1.3.1/lib/*.dylib
```
必须用多架构编译的库替换安装的静态库。您可以从以下github回复获取libogg这里和opus这里

用编译后的库替换目前安装的libogg和libopus库

rm -f /usr/local/Cellar/libogg/1.3.4/lib/libogg.a && cp ~/Downloads/libogg.a /usr/local/Cellar/libogg/1.3.4/lib

rm -f /usr/local/Cellar/opus/1.3.1/lib/libopus.a && cp ~/Downloads/libopus.a /usr/local/Cellar/opus/1.3.1/lib

如果在执行上述步骤之前遇到构建错误或已导入软件包，则可能需要重新索引项目。从您的XCode项目文件中的Swift Packages下移除WatsonDeveloperCloud软件包；然后，在屏幕顶部的XCode菜单栏上点击Product -> Clean Build Folder，最后重新安装软件包。
您已准备就绪！

Cocoapods

您可以使用RubyGems 安装Cocoapods。

$ sudo gem install cocoapods

如果您的项目还没有Podfile，请使用项目根目录下的pod init命令。要使用Cocoapods安装Swift SDK，将您将要使用的服务添加到以下示例所示的Podfile中（将MyApp替换为您的应用程序名称）。以下示例显示了所有当前可用的服务；您的Podfile应仅包含应用程序将使用的服务。

use_frameworks!

target 'MyApp' do
    pod 'IBMWatsonAssistantV1', '~> 5.0.0'
    pod 'IBMWatsonAssistantV2', '~> 5.0.0'
    pod 'IBMWatsonDiscoveryV1', '~> 5.0.0'
    pod 'IBMWatsonLanguageTranslatorV3', '~> 5.0.0'
    pod 'IBMWatsonNaturalLanguageUnderstandingV1', '~> 5.0.0'
    pod 'IBMWatsonSpeechToTextV1', '~> 5.0.0'
    pod 'IBMWatsonTextToSpeechV1', '~> 5.0.0'
end

运行pod install命令，并打开生成的.xcworkspace文件。要更新到更新的版本，请使用pod update。

在源文件中导入框架时，排除IBMWatson前缀和版本后缀。例如，安装IBMWatsonAssistantV1后，在源文件中将其导入为import Assistant。

有关使用Cocoapods的更多信息，请参阅Cocoapods指南。

Carthage

注意：苹果公司新M1芯片的发布导致Carthage（针对XCode 11+版本）出现了一些问题。在可预见的未来，我们无法通过Carthage支持XCode 11。我们建议您通过Swift Package Manager（首选）或升级到XCode 12（其中存在解决方案）进行安装。

注意：我们目前无法通过Carthage在新的苹果硅Mac上运行我们的框架。再次建议您使用Swift Package Manager。

您可以使用Homebrew 安装Carthage。

$ brew update
$ brew install carthage

如果您的项目还没有Cartfile，请使用项目根目录下的touch Cartfile命令。要安装IBM Watson Swift SDK使用Carthage，请将以下内容添加到您的Cartfile中。

github "watson-developer-cloud/swift-sdk" ~> 5.0.0

请按照XCode 12的工作区解决方案的剩余Carthage安装说明此处进行。然后运行以下命令来构建依赖项和框架

$ carthage.sh bootstrap --platform iOS

请注意，上述命令将下载并构建IBM Watson Swift SDK中的所有服务，会花费一定时间。

按照以下步骤将框架链接到您的XCode项目

请确保将构建的框架（仅为您应用程序所需的服务）拖放到XCode项目中的“常规 -> 框架、库和嵌入内容”下（XCode <= 10.x: 常规 -> 链接的框架和库），并在需要它们的源文件中导入它们。您可以在源目录的./Carthage/Build/iOS下找到.framework文件。
以下框架需要添加到您的应用程序中：IBMSwiftSDKCore.framework

您的应用程序将使用任何服务（例如：AssistantV1.framework、DiscoveryV1.framework等）

(仅限“语音到文本”）Starscream.framework。请确保将此框架添加到您的input.xcfilelist和output.xcfilelist中，具体细节将在下文介绍
仅XCode 12：在“嵌入”列中，请确保每个框架设置为“不嵌入”
在您的应用程序目标的“构建阶段”设置选项卡中，单击“+”图标并选择“新建运行脚本阶段”。创建一个运行脚本，在其中指定您的shell（例如：/bin/sh），在shell下面的脚本区域中添加以下内容：
```
/usr/local/bin/carthage copy-frameworks
```
创建一个名为input.xcfilelist的文件和一个名为output.xcfilelist的文件

将您要使用的框架的路径添加到您的input.xcfilelist中。例如：

$(SRCROOT)/Carthage/Build/iOS/IBMSwiftSDKCore.framework
$(SRCROOT)/Carthage/Build/iOS/DiscoveryV1.framework

将复制的框架的路径添加到output.xcfilelist中。例如：
```
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/IBMSwiftSDKCore.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/DiscoveryV1.framework
```
指定输入文件和输出文件后，XCode只有在输入文件已更改或输出文件缺失时才需要运行脚本。这意味着在您没有用Carthage重建框架时，脏构建将会更快。
将input.xcfilelist的路径添加到Carthage运行脚本阶段的“输入文件列表”部分。这通常将是$(SRCROOT)/input.xcfilelist
将output.xcfilelist的路径添加到Carthage运行脚本阶段的“输出文件列表”部分。这通常将是$(SRCROOT)/output.xcfilelist

如果您的应用程序因使用与下载的SDK不同的Swift版本而无法构建，请带有--no-use-binaries标志重新运行carthage.sh bootstrap命令。

身份验证

为了在Swift应用程序中使用IBM Watson服务，您需要进行身份验证。以下描述了您需要采取的典型步骤。

第1步：获取凭据

要使用IBM Watson服务，您需要通过IBM Cloud获取凭据。在身份验证Swift应用程序之前，您需要一个有效的账户以及您希望使用的服务的服务实例。

您可以按照以下步骤访问实例的服务凭据：

访问IBM Cloud 仪表板页面。
在您的资源列表中点击现有的Watson服务实例，或者点击创建资源 > AI来创建一个服务实例。
点击您的服务实例左侧导航栏中的“管理”项。

在页面上，您将看到用于通过SDK访问服务实例的凭据。

第2步：代码身份验证

Watson Swift SDK使用Authenticator类来管理身份验证。根据您选择的方法，有多种身份验证器类型。

WatsonIAMAuthenticator（最常用）

WatsonIAMAuthenticator允许您使用IAM API密钥进行身份验证。这是IBM Cloud中最常见的身份验证形式。在初始化方法中，WatsonIAMAuthenticator需要一个apikey字符串。

示例

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

...

WatsonBearerTokenAuthenticator

您可能希望提供 bearer 令牌以对服务进行身份验证。在IBM Cloud中，这将使用IAM服务根据您的服务凭据生成令牌来执行。在Cloud Pak for Data中，它将在单个服务实例中可用。

要在Swift应用中使用访问令牌进行身份验证，您可以使用WatsonBearerTokenAuthenticator并提供令牌。

示例

let authenticator = WatsonBearerTokenAuthenticator(bearerToken: "{token}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

...

WatsonCloudPakForDataAuthenticator

如果您正在使用IBM Cloud Pak for Data（CP4D）而不是公共IBM Cloud，则可以使用WatsonCloudPakForDataAuthenticator对您的CP4D集群进行身份验证。与接受bearer令牌的WatsonBearerTokenAuthenticator不同，WatsonCloudPakForDataAuthenticator接受CP4D集群本身的用户名和密码。

示例

let authenticator = WatsonCloudPakForDataAuthenticator(username: "{username}", password: "{password}", url: "https://{cpd_cluster_host}{:port}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

...

从环境变量检测身份验证

SDK可以从环境中提取服务凭据，例如VCAP_SERVICES环境变量或本地凭据文件。

要使用存储在本地文件的凭据，请转到您的IBM Cloud服务实例的“管理”标签，然后点击下载凭据的按钮。文件将被命名为ibm-credentials.env。将此文件添加到您的项目可访问的位置。对于iOS应用，请确保将其添加到应用程序目标中。

let assistant = Assistant(version: "your-version") // by calling the init method without an authenticator, the SDK will search for environment variables

...

如果您正在使用多个Watson服务，则可以将ibm-credentials.env文件的内容合并到一个文件中。文件中的行可以添加、删除或重新排序，但不能更改每行内容。

关于认证方法的更多信息

要获取进一步细节和较少使用的认证形式，请参阅IBM Swift SDK Core认证器的代码。

自定义服务URL

您可以通过修改serviceURL属性来设置自定义服务URL。在某些区域运行实例或通过代理连接时可能需要自定义服务URL。

例如，以下是如何连接到托管在德国的Watson Assistant实例的方法：

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

assistant.serviceURL = "https://api.eu-de.assistant.watson.cloud.ibm.com"

禁用SSL证书验证

对于Watson Cloud Pak for Data (CP4D)，如果您使用的是自签名证书，则可能需要禁用SSL主机名验证。每个服务类都有一个disableSSLVerification方法，允许您这样做。

let authenticator = WatsonCloudPakForDataAuthenticator(username: "{username}", password: "{password}", url: "https://{cpd_cluster_host}{:port}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

assistant.disableSSLVerification()

注意：disableSSLVerification()目前不支持Linux。

获取事务ID

当您正在与IBM支持人员进行问题调试时，您可能需要提供事务ID以帮助IBM识别需要调试的API调用。

每个SDK调用都会在X-Global-Transaction-Id标题中返回一个包含事务ID的响应。该服务实例的区域与该ID一起，帮助支持团队从相关日志中解决问题。

您可以通过以下模式访问头部

import AssistantV1

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "2020-04-01", authenticator: authenticator)
assistant.serviceURL = "{url}"

let input = MessageInput(text: "Hello")

// let's say this request isn't working and you need the transaction ID
assistant.message(workspaceID: "{workspace_id}", input: input) {
  response, error in

  print(response?.headers["X-Global-Transaction-Id"]!)

  ...
}

但是，当API由于某些原因没有返回响应时，交易ID不可用。在这种情况下，您可以在请求中设置自己的交易ID。例如，在以下示例中将<my-unique-transaction-id>替换为唯一的交易ID。

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "2020-04-01", authenticator: authenticator)
assistant.serviceURL = "{url}"

let input = MessageInput(text: "Hello")

assistant.message(workspaceID: "{workspace_id}", input: input, headers: ["X-Global-Transaction-Id": "<my-unique-transaction-id>"]) {
  response, error in

  print(response?.headers["X-Global-Transaction-Id"]!)

  ...
}

自定义头部

可以向沃森服务发送不同的头部。例如，沃森服务记录请求及其结果，以改进服务，但您可以通过包括X-Watson-Learning-Opt-Out头部来放弃这一选择。

每个类中已公开暴露一个defaultHeaders公共属性，以便用户可以轻松自定义他们的头部。

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

assistant.defaultHeaders = ["X-Watson-Learning-Opt-Out": "true"]

每个服务方法还接受一个可选的headers参数，它是一个请求头部的字典，将与请求一起发送。

疑问

如果您遇到API问题或对沃森服务有任何疑问，请参阅Stack Overflow。

特色项目

我们很乐意突出展示使用此SDK的酷炫开源项目！如果您想将您的项目添加到列表中，请随意创建一个问题，并链接给我们。

同步执行

默认情况下，SDK异步执行所有网络操作。如果您的应用程序需要同步执行，您可以使用DispatchGroup。例如

let dispatchGroup = DispatchGroup()
dispatchGroup.enter()
assistant.message(workspaceID: workspaceID) { response, error in
	if let error = error {
        print(error)
    }
    if let message = response?.result else {
        print(message.output.text)
    }
    dispatchGroup.leave()
}
dispatchGroup.wait(timeout: .distantFuture)

在XCode中处理PNG和CgBI文件

在处理iOS项目时，您可能需要在XCode资源包中添加PNG图像。默认情况下，XCode会将PNG文件转换为苹果的CgBI文件格式作为优化步骤。

如何绕过资源文件中的CgBI编码

为了绕过CgBI编码并保持PNG文件与Watson服务良好运行的格式，请在XCode中选择PNG文件，并在文件检查器中将《编码格式》属性修改为《数据》。

例：

CgBI处理未来的计划

未来，我们将探索在Swift SDK中处理CgBI和PNG之间的转换，但当前不可用。

Objective-C兼容性

有关更多信息，请参阅本教程，了解在Objective-C应用程序中消费Watson Developer Cloud Swift SDK。

Linux兼容性

要使用Watson SDK在您的Linux项目中，请按照Swift包管理器说明进行操作。注意，语音识别和语音合成不支持，因为它们依赖于Linux上不可用的框架。

贡献

我们非常欢迎任何形式和大小的帮助！如果您想贡献，请阅读我们的贡献指南，了解如何开始。

许可协议

此库遵循Apache 2.0许可协议。完整的许可协议文本可在LICENSE中查看。

此SDK适用于与Apple iOS产品一起使用，并旨在与官方授权的Apple开发工具配合使用。

IBMWatsonDiscoveryV1 5.0.0

IBMWatsonDiscoveryV1 5.0.0

IBMWatsonDiscoveryV1 5.0.0

Watson 开发者云 Swift SDK

已弃用的构建

概述

服务

公告

语调分析器弃用

自然语言分类器弃用

在开始之前

要求

安装

Swift包管理器

Cocoapods

Carthage

身份验证

第1步：获取凭据

第2步：代码身份验证

WatsonIAMAuthenticator（最常用）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

从环境变量检测身份验证

关于认证方法的更多信息

自定义服务URL

禁用SSL证书验证

获取事务ID

自定义头部

疑问

特色项目

同步执行

在XCode中处理PNG和CgBI文件

如何绕过资源文件中的CgBI编码

CgBI处理未来的计划

Objective-C兼容性

Linux兼容性

贡献

许可协议