# 与其他 Unity 服务集成

> Integrate Cloud Code with various Unity Gaming Services using C# Software Development Kits or REST APIs.

为了充分发挥 Cloud Code 的潜力，您可以使用 C# Service SDK 或 REST API 将其与各种 Unity Gaming Services（Unity 游戏服务）无缝集成。

C# SDK 提供了更简单、更一致的体验，可以方便地访问 Unity Gaming Services（Unity 游戏服务）。如果您希望使用的 Unity Gaming Services（Unity 游戏服务）已经有 Cloud Code C# SDK，您可以利用它实现更顺畅的集成。但是，如果特定 UGS 服务缺少 Cloud Code C# SDK，您可以灵活地通过其 REST API 直接与其连接。

## 通过 UGS SDK 连接到 UGS##connect-to-ugs-through-the-ugs-sdks

要从 NuGet 访问 Cloud Code C# 服务 SDK，请搜索 [Com.Unity.Services.CloudCode.Apis](https://www.nuget.org/packages/Com.Unity.Services.CloudCode.Apis)。安装该包后，您可以在 C# 模块中使用该包来简化与其他 Unity 服务的连接方式。

> **Note:**
>
> **注意**：Cloud Code C# SDK 的文档尚未完成。如需了解更多信息，可以参阅 [JavaScript 文档](../../scripts/how-to-guides/unity-services-integration)，其具有类似的结构。此外，请利用集成开发环境的自动补全和智能感知功能。

如需查看 Cloud Code C# SDK 的完整列表，请参阅[可用库](../reference/available-libraries)页面。

### API 客户端##api-clients

`GameApiClient` 和 `AdminApiClient` 类都是 Cloud Code C# SDK 的包装器，为从 Cloud Code 模块调用 Unity Gaming Services（Unity 游戏服务）(UGS) 提供了简化的接口。然而，它们的用途不同，针对不同的用例而设计。

### 使用 `GameApiClient` 类##use-the-gameapiclient-class

`GameApiClient` 类是专为与 UGS 提供的标准游戏服务进行交互而定制的。通过该类可以方便地从与玩家特定功能（例如保存和获取游戏数据）相关的 Cloud Code 模块调用 UGS 服务。在提供的示例中，该类用于与 Cloud Save 功能交互，演示了如何保存和获取玩家数据。

要使用 `GameApiClient` 接口，请在 `ICloudCodeSetup` 配置器中将 `GameApiClient` 注册为[单例](./initialize-modules/dependency-injection.md)：

```csharp
public class ModuleConfig : ICloudCodeSetup
{
    public void Setup(ICloudCodeConfig config)
    {
        config.Dependencies.AddSingleton(GameApiClient.Create());
    }
}
```

#### 用法示例##usage-example

您可以在归属于 `CloudCodeFunction` 的任何函数中使用 `GameApiClient` 类。要使用 `GameApiClient` 类，请将 `IGameApiClient` 接口作为参数传入函数。

以下示例演示了如何在 Cloud Save 中保存和读取数据：

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Unity.Services.CloudCode.Apis;
using Unity.Services.CloudCode.Core;
using Unity.Services.CloudCode.Shared;
using Unity.Services.CloudSave.Model;

namespace ExampleModule;

public class CloudSaveSdkSample
{
    private static ILogger<CloudSaveSdkSample> _logger;

    public CloudSaveSdkSample(ILogger<CloudSaveSdkSample> logger)
    {
        _logger = logger;
    }

    [CloudCodeFunction("SaveData")]
    public async Task SaveData(IExecutionContext context, IGameApiClient gameApiClient, string key, object value)
    {
        try
        {
            await gameApiClient.CloudSaveData.SetItemAsync(context, context.AccessToken, context.ProjectId,
                context.PlayerId, new SetItemBody(key, value));
        }
        catch (ApiException ex)
        {
            _logger.LogError("Failed to save data. Error: {Error}", ex.Message);
            throw new Exception($"Failed to save data for playerId {context.PlayerId}. Error: {ex.Message}");
        }
    }

    [CloudCodeFunction("GetData")]
    public async Task<object> GetData(IExecutionContext context, IGameApiClient gameApiClient, string key)
    {
        try
        {
            var result = await gameApiClient.CloudSaveData.GetItemsAsync(context, context.AccessToken,
                context.ProjectId, context.PlayerId, new List<string> { key });
            return result.Data.Results.First().Value;
        }
        catch (ApiException ex)
        {
            _logger.LogError("Failed to get data. Error: {Error}", ex.Message);
            throw new Exception($"Failed to get data for playerId {context.PlayerId}. Error: {ex.Message}");
        }
    }

    public class ModuleConfig : ICloudCodeSetup
    {
        public void Setup(ICloudCodeConfig config)
        {
            config.Dependencies.AddSingleton(GameApiClient.Create());
        }
    }
}
```

### 使用 `AdminApiClient` 类##use-the-adminapiclient-class

`AdminApiClient` 类用于访问 UGS 服务的管理功能。该类提供了一个简化的接口以从 Cloud Code 模块调用与管理相关的 UGS 服务。此处的示例说明了如何使用 AdminApiClient 创建排行榜，展示了其在管理任务中的实用性。

要使用 `AdminApiClient` 接口，请在 `ICloudCodeSetup` 配置器中将 `AdminApiClient` 注册为[单例](./initialize-modules/dependency-injection.md)：

```csharp
public class ModuleConfig : ICloudCodeSetup
{
    public void Setup(ICloudCodeConfig config)
    {
        config.Dependencies.AddSingleton(AdminApiClient.Create());
    }
}
```

#### 用法示例##usage-example

与 `GameApiClient` 类似，`AdminApiClient` 类可用于任何带有 CloudCodeFunction 属性的函数。在使用 `AdminApiClient` 类时，请将 `IAdminApiClient` 接口作为参数传入函数。

> **Note:**
>
> **注意**：要通过 Admin SDK 使用管理功能，您需要一些具有 `Leaderboards Admin` 项目角色的有效服务帐户凭据。要创建服务帐户，请参阅[管理员身份验证](https://services.docs.unity.com/docs/service-account-auth/)。

> **Important:**
>
> **警告**：此 Cloud Code 示例演示了如何使用硬编码的纯文本服务帐户凭据。处理凭据和包含密钥的代码时，请务必小心谨慎。为了确保安全，建议您不要将密钥提交到版本控制系统。如果您的凭据被泄露，您可以立即重新生成您的服务帐户凭据。目前正在开发一种在 Cloud Code 中存储凭据的更安全的方法。

以下示例演示了如何创建排行榜：

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Unity.Services.CloudCode.Apis;
using Unity.Services.CloudCode.Apis.Admin;
using Unity.Services.CloudCode.Core;
using Unity.Services.CloudCode.Shared;
using Unity.Services.Leaderboards.Admin.Model;

namespace ExampleModule;

public class ModuleMain
{
    private static ILogger<ModuleMain> _logger;

    public ModuleMain(ILogger<ModuleMain> logger)
    {
        _logger = logger;
    }

    [CloudCodeFunction("CreateLeaderboard")]
    public async Task CreateLeaderboard(IExecutionContext context, IAdminApiClient adminApiClient)
    {
        try
        {
            await adminApiClient.Leaderboards.CreateLeaderboardAsync(
                executionContext: context,
                serviceAccountKey: "YOUR_SERVICE_ACCOUNT_KEY",
                serviceAccountSecret: "YOUR_SERVICE_ACCOUNT_SECRET",
                projectId: Guid.Parse(context.ProjectId),
                environmentId: Guid.Parse(context.EnvironmentId),
                leaderboardIdConfig: new LeaderboardIdConfig(
                    id: "new-leaderboard",
                    name: "new-leaderboard",
                    sortOrder: SortOrder.Asc,
                    updateType: UpdateType.KeepBest
                )
            );
        }
        catch (ApiException ex)
        {
            _logger.LogError("Failed to create a Leaderboard. Error: {Error}", ex.Message);
            throw new Exception($"Failed to create a Leaderboard. Error: {ex.Message}");
        }
    }

    public class ModuleConfig : ICloudCodeSetup
    {
        public void Setup(ICloudCodeConfig config)
        {
            config.Dependencies.AddSingleton(AdminApiClient.Create());
        }
    }
}

```

## 通过 REST API 连接到 UGS##connect-to-ugs-through-rest-apis

如果要使用尚无 C# SDK 的服务，也可以通过 REST API 直接与服务进行连接。

### 身份验证##authentication

根据您的用例，您可以使用 `AccessToken` 或 `ServiceToken` 对 API 调用进行身份验证。如果使用 `ServiceToken` 对 UGS Client API 进行身份验证，请确保要调用的服务支持服务令牌。如需查看支持服务令牌的服务和用例的列表，请参阅[服务令牌和访问令牌支持](./token-support.md)文档。

> **Note:**
>
> **注意**：如果要调用的服务提供了 Cloud Code C# SDK，则可以使用该 SDK，而不是直接调用服务 API。如需了解更多信息，请参阅[可用库](../reference/available-libraries)列表。

### 调用 API##calling-the-api

通过[依赖项注入](./initialize-modules/dependency-injection.md)可以将 API 接口创建为单例，并将它们注入到模块中。

> **Note:**
>
> 除了 UGS API 之外，还可以将外部 API 实现为单例。如需查看如何实现外部 API 的示例，请参阅有关如何[与外部服务集成](./external-services-integration.md)的文档。