Watson Developer Cloud Swift SDK

已弃用的构建

概述

Watson Developer Cloud Swift SDK 使移动开发者轻松构建具有 Watson 功能的应用程序。使用 Swift SDK，您可以利用 Watson 的高级人工智能、机器学习和深度学习技术，以新的方式理解非结构化数据并参与与移动用户互动。

有许多资源可以帮助您使用 Swift SDK 构建 cognitive 应用程序的第一个版本

查看一个特色项目
浏览文档

服务

此 SDK 提供类和方法来访问以下 Watson 服务：

公告

语调分析器弃用

从这次主要版本5.0.0开始，为准备弃用，已经删除了Tone Analyzer API。如果您希望在弃用最终生效前继续使用此SDK调用电调Tone分析器，您将需要使用以前的版本。

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

作为替代方案，我们鼓励您考虑迁移到IBM云上的自然语言理解服务。在自然语言理解中，语调分析通过使用预构建的分类模型来完成，这提供了一种方便的方法来检测书面文本中的语言语调。有关更多信息，请参阅从Watson Tone分析器客户参与端点迁移到自然语言理解。

自然语言分类器弃用

从这次主要版本5.0.0开始，为准备弃用，已经删除了NLC API。如果您希望在弃用最终生效前继续使用此SDK调用自然语言分类器，您将需要使用以前的版本。

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

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

在开始之前

您需要一个IBM Cloud账户。

要求

Xcode 10.2+
Swift 5.0+
iOS 10.0+

安装

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

Swift Package Manager

New in version 4.0.2, the Watson Developer Cloud Swift SDK now supports all services through Swift Package Manager.

在屏幕顶部的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芯片的发布导致XCode 11+版本的Carthage出现问题。在可预见的未来，我们无法通过Carthage支持XCode 11。我们建议使用Swift包管理器（首选）或升级到XCode 12（其中有一些解决方案）。

注意：当前无法通过Carthage在新的苹果硅Mac上运行我们的框架。再次提醒，我们建议使用Swift包管理器。

您可以使用Homebrew安装Carthage。

$ brew update
$ brew install carthage

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

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

按照以下链接中的XCode 12解决方案的剩余Carthage安装说明操作这里。然后运行以下命令来构建依赖和框架

$ carthage.sh bootstrap --platform iOS

注意，上述命令将下载和构建IBM Watson Swift SDK中的所有服务，可能需要一些时间。

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

请确保将构建的框架（仅适用于您的应用程序需要的服务）拖放到应用程序目标下的 General -> Frameworks, Libraries, and Embedded Content（XCode <= 10.x: General -> Linked Frameworks and Libraries）中，并在需要这些框架的源文件中导入它们。您可以从源目录下的 ./Carthage/Build/iOS 中找到 .framework 文件。
以下框架需要添加到您的应用程序中：IBMSwiftSDKCore.framework

您的应用程序将使用哪些服务（AssistantV1.framework，DiscoveryV1.framework，等等）

(仅语音转文字) Starscream.framework。请确保将其添加到您的 input.xcfilelist 和 output.xcfilelist，这些将在下面详细说明
仅限 XCode 12：在 Embed 列中，确保每个框架都已设置为 Do Not Embed
在应用程序目标的构建阶段设置标签页中，点击 + 图标并选择新建 Run Script 阶段。在脚本区域下方指定您的 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
```
当输入文件已更改或输出文件丢失时，仅在此情况下运行脚本，以确保输出文件。这意味着在没有使用 Carthage 重新构建框架时，脏构建将更快
将 input.xcfilelist 的路径添加到 Carthage 运行脚本阶段的 "Input File Lists"（输入文件列表）部分。这通常为 $(SRCROOT)/input.xcfilelist
将 output.xcfilelist 的路径添加到 Carthage 运行脚本阶段的 "Output File Lists"（输出文件列表）部分。这通常为 $(SRCROOT)/output.xcfilelist

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

Authentication

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

第一步：获取凭证

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

您可以通过以下步骤获取实例的服务凭证

前往 IBM Cloud 仪表板页面。
在您的资源列表中点击现有的 Watson 服务实例，或者点击 新建资源 > AI 创建服务实例。
点击服务实例左侧导航栏中的管理项目。

在此页面上，您将看到SDK访问服务实例所需的凭证。

步骤 2：代码中进行认证

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

WatsonIAMAuthenticator（最常用）

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

示例

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

...

WatsonBearerTokenAuthenticator

您可能需要提供访问令牌以对服务进行身份验证。在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，则可以使用《code>WatsonCloudPakForDataAuthenticator来对CP4D集群进行身份验证。与接受访问令牌的《code>WatsonBearerTokenAuthenticator相反，《code>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云上服务实例的管理标签页，然后点击下载凭据的按钮。文件将命名为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上不受支持。

获取事务标识

当您向IBM技术支持调试问题时，可能导致您需要提供事务标识来帮助IBM定位需要调试的API调用。

每个SDK调用都会在响应的X-Global-Transaction-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由于某种原因没有响应时，事务标识不可用。在这种情况下，您可以在请求中设置自己的事务标识。例如，将以下示例中的<my-unique-transaction-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"]!)

  ...
}

自定义头部信息

您可以发送不同的头部信息到Watson服务。例如，Watson服务会记录请求及其结果以改进服务，但您可以通过包含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时遇到问题或对Watson服务有疑问，请参阅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文件转换为Apple的CgBI文件格式作为优化步骤。

如何为资源文件绕过CgBI编码

为了绕过CgBI编码并将PNG文件保持在与Watson服务兼容的格式中，在XCode中选择PNG文件，并在“文件检查器”中将“类型”属性修改为“数据”。

例如

CgBI处理的发展计划

未来，我们将探索在Swift SDK内部处理CgBI和PNG转换的选项，但目前此功能尚未提供。

Objective-C兼容性

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

Linux 兼容性

要在 Linux 项目中使用 Watson SDK，请按照Swift Package Manager 指令操作。请注意，由于它们依赖于 Linux 上不可用的框架，语音到文本和文本到语音功能不支持。

贡献

我们欢迎任何形式和任何程度的帮助！如果您想贡献，请阅读我们的CONTRIBUTING文档，以获取有关开始的详细信息。

许可

本库受 Apache 2.0 许可协议许可。完整许可文本可在LICENSE中找到。

此 SDK 用于与 Apple iOS 产品搭配使用，并旨在与官方许可的 Apple 开发工具结合使用。

IBM Watson Assistant V2 5.0.0

IBM Watson Assistant V2 5.0.0

IBM Watson Assistant V2 5.0.0

Watson Developer Cloud Swift SDK

已弃用的构建

概述

服务

公告

语调分析器弃用

自然语言分类器弃用

在开始之前

要求

安装

Swift Package Manager

Cocoapods

Carthage

Authentication

第一步：获取凭证

步骤 2：代码中进行认证

WatsonIAMAuthenticator（最常用）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

从环境变量中检测身份验证

关于身份验证方法的更多信息

自定义服务URL

停用SSL证书验证

获取事务标识

自定义头部信息

问题

特色项目

同步执行

在XCode中处理PNG和CgBI文件

如何为资源文件绕过CgBI编码

CgBI处理的发展计划

Objective-C兼容性

Linux 兼容性

贡献

许可