# V1 到 V2 迁移指南

> Migrate from Vivox server-side recording version 1 to version 2.

如果要对服务器端录制 API 版本 1 进行升级，请遵循本指南。

## 重要更改##key-changes

V2 API 进行了以下更改：

* TTL 不再是有效选项，必须对所有请求均使用历史记录。
* 该 API 现在支持使用 GCP 存储桶进行存储。
* 该 API 已重新设计，更加符合 REST 风格：
  * 状态完整文件现已被回调服务器取代。
* SSR 现在需要使用来自 Unity Cloud 组织的服务帐户。
* 重复数据删除功能已被移除。您将不再看到关于重复请求的 `409` 错误代码。
* 自动结束功能已被移除。请求将始终在历史记录请求的整个持续时间内运行。
* 您无需再发出解码音频的请求。Vivox 将为您管理相关状态，最终结果将是频道中每个扬声器对应有一个 .WAV 文件。

## Authentication 更改##authentication-changes

1. SSR 现在要求所有请求都要使用 Unity Authentication。
   * 如果尚未创建组织或项目，请创建一个。请参阅 如何创建项目 以了解更多信息。

2. 拥有项目和组织后，需要将详细信息分享给您的客户经理。您的客户经理将为您的组织启用 SSR。

3. 启用 SSR 后，您需要创建一个服务帐户以进行 API 身份验证。请参阅[如何创建服务帐户](https://services.docs.unity.com/docs/service-account-auth/#create-a-service-account)。

4. 在服务帐户页面上，为服务帐户分配权限。选择 **Manage organization permissions** 并分配 `Server Side Recording Processor Role`。这样，该服务帐户便能访问 SSR API。


   **启用 SSR 权限的示例，从下拉选单中进行选择。:**
   ![启用 SSR 权限的示例，从下拉选单中进行选择。](/api/media?file=/vivox-unity/media/images/Unity/server-side-recording/images/ssr-permission.png)

5. 要使用此服务帐户，请参阅[如何使用服务帐户进行身份验证](https://services.docs.unity.com/docs/service-account-auth/#authenticate-an-api-using-service-account-credentials)。

## API 更改##api-changes

> **Note:**
>
> [SSR v2 的完整 API 文档](https://services.docs.unity.com/ssr/v2/)可在 Web Services API 文档站点中找到。
>
> 本指南仅涵盖从 V1 API 到 V2 API 的更改，不介绍任何新增功能。请参阅完整的 API 文档以了解新字段和选项的概述。

### 请求更改##request-changes

V2 API 移除了用于传递请求字段的查询参数。现在，所有字段均以 JSON 形式传递到请求正文中。下面列出了不再存在的字段。

1. `destination_credentials` 现在包含在 `storageOptions` 中。要按照与 V1 API 相同的方式使用 AWS，必须替换特定的代码段。

   | 替换此代码                                                                                                                        | 替换为此代码                                                                                                                                         |
   | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
   | \{  "destination\_credentials": \{ "bucket": "my-bucket",  "access\_key\_id": "secret", "secret\_access\_key": "secret" }  } | \{ "storageOptions": \{ "provider": "aws", "credentials": \{ "bucket": "my-bucket", "accessKeyId": "secret", "secretAccessKey": "secret" } } } |

2. 移除 `target_type` 字段。V2 API 仅支持频道订阅。

3. `ttl` 字段已被移除。现在使用 `history` 字段指定录音的持续时间。

> **Note:**
>
> 添加了一个可选字段 `callbackUri`。此字段可以指定一个回调服务器，以便将作业状态接收到您托管的服务器上。您可以在此字段中指定任何 URL，Vivox 会向其发出请求。如需了解更多信息，请参阅[回调服务器文档](./callback-server.md)。

## SSR 解码器##ssr-decoder

SSR 解码器不再是单独的请求。请求的最终结果将是频道中每个扬声器对应有一个 .WAV 文件，并且您可以从基础结构中移除作业状态跟踪功能。

## 回调服务器##callback-server

删除 `status_complete` 和 `status_decoded` 后，添加了一种机制以便在作业完成时通知您。这是通过回调服务器实现的。如需了解更多信息，请参阅[回调服务器文档](./callback-server.md)。

此功能完全是可选的功能，但也是了解作业完成时间或音频丢失原因的唯一方法。