告警通知服务 SDK

告警通知服务 SDK 允许 Swift 开发者在其应用程序中使用告警通知 IBM Cloud 服务，从而可以主动修复在 IBM Cloud 上运行的应用程序的问题。 通过使用此 SDK，可以创建、接收和删除告警和消息。 该服务可以通过此链接获取，文档可以在此链接获取；这两个链接可能需要 IBM Cloud 帐户才能访问。 非 IBM Cloud 快速入门指南可以在 IBM 网站上查看。

此 SDK 用于使用告警通知服务，而不是用于管理该服务。 添加用户、组、通知策略等应该通过 IBM Cloud 仪表板完成。

告警通知 SDK 适用于 Swift 二进制文件的 4.1.2 发行版本。 您可以从 Swift.org 下载此版本。

为了使用此 SDK，您需要将其添加到应用程序的 Package.swift 文件中的依赖项中。

import PackageDescription

let package = Package(
    name: "MyAlertEnabledSwiftProject",

    ...

    dependencies: [
        .package(url: "https://github.com/IBM-Swift/alert-notification-sdk.git", .upToNextMajor(from: "2.0.0")),
        ...
    ]
    ...
)

更新 Package.swift 文件后，将 AlertNotifications 模块导入到您的项目中。

为了使用告警通知 SDK 的所有功能，您需要一个告警通知服务的实例（请注意这只是付费服务）。 获得此服务实例后，从您的 IBM Cloud 仪表板中选择它，然后单击“服务凭据”选项卡。 如果您还没有凭据，请创建一个。

创建凭据后，选择“查看凭据”并记下其中显示的信息。 您的应用程序将需要完整的 name 和 password 字段，但 **您应该只使用 url 字段直到且包含 /api**。 不要包含 url 中在此之后出现的任何部分。

使用这些信息，您应该在您的应用程序中创建一个 ServiceCredentials 对象，它将用于创建、检索或删除告警或消息的所有函数中。

let credentials = ServiceCredentials(url: "<url>", name: "<name>", password: "<password>")

Alert 类用于指定告警的单个实例。 Alert 具有以下必需属性

• summary - 一个 String，它提供告警的简短描述。
• location - 一个 String，它描述导致告警的条件发生的区域。
• severity - Alert.Severity 类型的属性，它描述告警的严重程度。

Alert 还可以由应用程序给定这些额外的可选属性

• id - 一个 String，它为这个告警提供一个唯一标识符，用于去重。
• date - 一个 Date 对象，指示告警何时引发。
• status - Alert.Status 类型的属性，指示告警是否已解决。 默认值为 .problem。
• source - 一个 String，指示告警条件的来源。
• applicationsOrServices - 一个 String 数组，指示哪些 IBM Cloud 应用程序或服务受到此告警的影响。
• URLs - 一个 Alert.URL 对象数组，提供与告警相关的其他链接。
• details - 一个 Alert.Detail 对象数组，提供额外的键值对作为与告警相关的详细信息。
• emailMessageToSend - 一个 Alert.EmailMessage 对象，指定在发布告警时要发送给收件人的电子邮件。 它可以选择使用 Mustache 模板进行格式化。
• SMSMessageToSend - 一个 String，指定在发布告警时要发送给收件人的 SMS 消息。 它可以选择使用 Mustache 模板进行格式化。
• voiceMessageToSend - 一个 String，指定在发布告警时要发送给收件人的语音消息。 它可以选择使用 Mustache 模板进行格式化。

最后，当 Alert 对象由告警通知服务发送时，它可能包含更多属性。 这些不能由应用程序设置。

• shortId - 告警通知服务设置的较短的标识 String。 这是应用程序尝试在告警上调用 GET 或 DELETE 请求时应使用的标识符。
• notificationState - Alert.NotificationState 类型的属性，指示告警当前所处的报告过程中的位置。
• firstOccurrence - 一个 Date 对象，指示此告警首次发送的时间。
• lastNotified - 一个 Date 对象，指示上次发送有关此告警的通知的时间。
• internalTime - 一个 Date 对象，指示此告警发布的时间。
• expired - 一个 Bool，指示告警是否仍然有效或已过期。 过期的告警不会出现在告警查看器 UI 中。

Alert 的所有属性都是不可变的。 一旦创建了 Alert，就不能修改它。 Alert.Builder 类可用于创建现有 Alert 的修改版本。

Alert.URL 对象用于提供告警旁边的其他信息链接，例如指向运行手册的链接。 Alert.URL 对象具有以下属性

• description - 链接的简短 String 描述。
• URL - 一个 String，包含链接的 URL。

Alert.URL 只有一个方法，即构造函数。

Alert.URL(description: String, URL: String)

Alert.Detail 对象用于以键值对的形式提供告警旁边的其他详细信息。 Alert.Detail 对象具有以下属性

• name - 一个 String，指示详细信息名称。
• value - 一个 String，指示相应的值。

Alert.Detail 只有一个方法，即构造函数。

Alert.Detail(name: String, value: String)

Alert.EmailMessage 对象用于指定要随告警一起发送的电子邮件。 Alert.EmailMessage 对象具有以下属性

• subject - 一个 String，包含主题行。
• body - 一个 String，包含电子邮件正文。

Alert.EmailMessage 只有一个方法，即构造函数。

Alert.EmailMessage(subject: String, body: String)

Alert.Severity 类型指示与告警关联的严重程度级别。 该类型是一个枚举，具有以下可能的值，如 告警通知服务文档 中所示

• .fatal - 发生了服务终止条件。 需要立即采取行动。
• .critical - 发生了影响服务的条件，需要立即采取纠正措施。 例如，设备已停止服务，需要恢复。
• .major - 发生了影响服务的问题。 迫切需要采取纠正措施。 例如，设备的容量严重下降，必须恢复完整容量。
• .minor - 发生了非服务影响问题； 采取纠正措施以防止出现更高严重级别的告警。 例如，设备上出现问题，但不会损害设备的容量或性能。
• .warning - 检测到潜在或即将发生的问题。 需要进一步调查以防止出现更高严重级别的告警。
• .indeterminate - 无法从设备确定严重程度级别。
• .clear - 表示告警已解决，由操作员手动解决，或由确定故障条件不再存在的进程自动解决。

Alert.Status 类型指示告警是否已被确认或解决。 该类型是一个枚举，具有以下可能的值

• .problem - 告警已发布，但尚未采取任何措施。
• .acknowledged - 告警已被查看和确认，并且正在采取措施解决它。
• .resolved - 告警已解决。

Alert.NotificationState 类型更详细地指示用户是否已收到问题通知。 该类型是一个枚举，具有以下可能的值

• .unnotified - 告警通知已收到告警，但未生成任何通知。 表示告警与任何现有的通知策略不匹配。
• .notified - 告警通知已将告警与通知策略匹配，并触发了通知，该通知已发送到通知策略中定义的用户或组。 没有任何联系人确认告警。 表示没有人正在处理告警。
• .acknowledged - 指示告警通知正在处理告警。 联系人已从通知或告警查看器中确认告警。 告警可以在已确认和未确认状态之间切换，例如，如果告警被错误地确认。
• .escalated - 通知策略中指定的时间段已过，但告警未被确认。 已将升级通知发送到通知策略中定义的用户或组。
• .archived - 告警当前已归档。 类型 = 解决方案的告警 API 请求会将告警转换为已归档状态。 当传入告警对超过八小时的现有告警进行去重时，现有告警将被归档（而不是传入告警）。

由于 Alert 类具有如此多的属性，因此提供了一个构建器类。 Alert.Builder 类是当前创建 Alert 对象或修改现有 Alert 的唯一方法（这将创建一个新对象，因为 Alert 对象是不可变的）。 构建器有两种不同的构造函数

• Alert.Builder() - 创建一个新构建器，所有属性都初始化为 nil。
• Alert.Builder(from: Alert) - 创建一个新的构建器，并将所有属性初始化为所提供的 Alert 中它们的值。

在构建过程中，以下方法将设置某些属性

• setSummary(_: String)
• setLocation(_: String)
• setSeverity(_: Alert.Severity)
• setID(_: String)
• setDate(_: Date)
• setDate(fromString: String) - 从格式化的日期字符串创建一个 Date 对象。该字符串必须具有 yyyy-MM-dd HH:mm:ss 格式。
• setDate(fromIntInMilliseconds: Int) - 从一个整数创建一个 Date 对象，该整数表示自 epoch 以来的毫秒数。
• setStatus(_: Alert.Status)
• setSource(_: String)
• setApplicationsOrServices(_: [String])
• setURLs(_: [Alert.URL])
• setDetails(_: [Alert.Detail])
• setEmailMessageToSend(_: Alert.EmailMessage)
• setSMSMessageToSend(_: String)
• setVoiceMessageToSend(_: String)

上述每个方法都返回一个 Alert.Builder 对象，因此它们可以链接在一起，如下例所示

Alert.Builder().setSummary("summary").setLocation("location").setSeverity(.fatal).build()

当所有所需的属性都设置完毕后，build() 函数将完成构建并返回一个 Alert 对象。如果 summary、location 或 severity 变量未设置，则 build() 将抛出错误。

AlertService 类是一个静态类，用于从 Alert Notification 服务创建、检索和删除警报。 所有 API 函数都是异步的，因此如果应用程序要使用从它们返回的数据，则必须提供回调函数。 为了通过服务进行身份验证，所有函数都需要一个 ServiceCredentials 对象（请参阅上面的“凭据设置”）。 提供了以下方法

AlertService.post(_: Alert, usingCredentials: ServiceCredentials, callback: ((Alert?, Error?) -> Void)? = nil) throws

将提供的 Alert 对象发布到 Alert Notification 服务。 该服务返回一个 Alert 对象，其中初始化了额外的字段，例如 shortId。 虽然是可选的，但必须包含一个带有签名 (Alert?, Error?) -> Void 的回调函数，以便查看此返回的警报或任何可能的错误。 此方法仅抛出在发出基础 POST 请求之前或在发出请求时发生的错误；在此之后发生的任何错误都将通过回调函数传递。

AlertService.get(shortId: String, usingCredentials: ServiceCredentials, callback: (Alert?, Error?) -> Void) throws

从 Alert Notification 服务检索与提供的 shortId 参数对应的 Alert 对象。 请注意，这与用于重复数据删除的 id 参数不同。 与 post 函数不同，此方法需要带有签名 (Alert?, Error?) -> Void 的回调函数。 此方法仅抛出在发出基础 GET 请求之前或在发出请求时发生的错误；在此之后发生的任何错误都将通过回调函数传递。

AlertService.delete(shortId: String, usingCredentials: ServiceCredentials, callback: ((Error?) -> Void)? = nil) throws

从 Alert Notification 服务删除与提供的 shortId 参数对应的 Alert 对象。 请注意，这与用于重复数据删除的 id 参数不同。 需要一个可选的回调函数，其签名为 (Error?) -> Void，以查看可能从 Alert Notification 服务返回的错误。 此方法仅抛出在发出基础 DELETE 请求之前或在发出请求时发生的错误；在此之后发生的任何错误都将通过回调函数传递。

Message 类用于指定与警报和警报通知相关的单个消息实例。 Message 具有以下必需的属性

• subject - 一个 String，用作消息的主题行。 其长度不能超过 80 个字符。
• message - 一个 String，用作消息的正文。 其长度不能超过 1500 个字符。
• recipients - 一个 Message.Recipient 对象数组，用于指定哪些人、组或集成将接收消息。

当 Message 由 Alert Notification 服务发送时，它可能包含两个额外的属性。 这些不能由应用程序设置。

• shortId - Alert Notification 服务设置的较短的标识 String。 这是应用程序在尝试调用消息的 GET 请求时应使用的标识符。
• internalTime - 一个 Date 对象，指示何时发布此消息。

Message 的所有属性都是不可变的。 一旦创建了 Message，就无法修改它。

与 Alert 类不同，Message 类没有构建器，而是使用简单的构造函数。 如果违反了对 subject 或 message 的长度限制，则构造函数将抛出错误。

Message(subject: String, message: String, recipients: [Message.Recipient]) throws

Message.Recipient 对象用于指定将接收消息的人、组或集成。 Message.Recipient 对象具有以下属性

• name - 一个 String，指定接收者的名称。
• type - 一个 Message.RecipientType 属性，指示此接收者的类型（请参阅下面的 Message.RecipientType）。
• broadcast - 一个 String，用于指示此接收者打算连接到哪个集成。 只有当 type 为 .integration 时，此属性才是必需的。

Message.Recipient 只有一个方法，即构造函数。 如果 type 为 .integration 且 broadcast 属性为 nil，则此构造函数将抛出错误。

Message.Recipient(name: String, type: Message.RecipientType, broadcast: String? = nil) throws

Message.RecipientType 类型指示 Message.Recipient 对象旨在用于哪种类型的接收者。 该类型是一个枚举，具有以下可能的值

• .user - 单个用户。
• .group - 用户组。
• .integration - 集成服务，例如 Slack。

MessageService 类是一个静态类，用于从 Alert Notification 服务创建和检索消息。 所有 API 函数都是异步的，因此如果应用程序要使用从它们返回的数据，则必须提供回调函数。 为了通过服务进行身份验证，所有函数都需要一个 ServiceCredentials 对象（请参阅上面的“凭据设置”）。 提供了以下方法

MessageService.post(_: Message, usingCredentials: ServiceCredentials, callback: ((Message?, Error?) -> Void)? = nil) throws

将提供的 Message 对象发布到 Alert Notification 服务。 该服务返回一个 Message 对象，其中初始化了额外的字段，例如 shortId。 虽然是可选的，但必须包含一个带有签名 (Message?, Error?) -> Void 的回调函数，以便查看此返回的消息或任何可能的错误。 此方法仅抛出在发出基础 POST 请求之前或在发出请求时发生的错误；在此之后发生的任何错误都将通过回调函数传递。

MessageService.get(shortId: String, usingCredentials: ServiceCredentials, callback: (Message?, Error?) -> Void) throws

从 Alert Notification 服务检索与提供的 shortId 参数对应的 Message 对象。 请注意，这与用于重复数据删除的 id 参数不同。 与 post 函数不同，此方法需要带有签名 (Message?, Error?) -> Void 的回调函数。 此方法仅抛出在发出基础 GET 请求之前或在发出请求时发生的错误；在此之后发生的任何错误都将通过回调函数传递。

ServiceCredentials 类用于指定 IBM Cloud 上 Alert Notification 服务的身份验证凭据。 这是传递给所有 AlertService 和 MessageService 函数的对象。 ServiceCredentials 对象具有以下必需属性，直接对应于 IBM Cloud 服务中找到的凭据（请参阅“凭据设置”部分）。

• url - SDK 将连接到的 URL，以便创建、检索和删除警报或消息。 请注意，您应该只包含服务凭据中提供的 URL，直到并包括 /api。
• name - 服务的用户名。
• password - 用于通过服务进行身份验证的密码。

所有 ServiceCredentials 属性都是不可变的，并且在创建对象后无法更改。 该对象只有一个方法，即构造函数

ServiceCredentials(url: String, name: String, password: String)

This Swift package is licensed under Apache 2.0. Full license text is available in LICENSE.