# 使用の準備

> Follow this workflow to set up Triggers and automate rewarding top players from Leaderboards.

このセクションでは、Triggers の使用を準備するために必要なすべてのステップについて説明します。

以下のサンプルは、Triggers を使用し、Scheduler によって発行された 1 回限りのスケジュールイベントを使用して [Cloud Save](/cloud-save.md) で [Leaderboards](/leaderboards.md) の上位 5 人のプレイヤーにシーズントロフィーを授与する方法を示します。

## ビデオウォークスルー##video-walkthrough

以下のビデオを見て、Unity Dashboard でトリガーを作成するステップのウォークスルーを確認してください。


[Video content](https://youtu.be/eTnxB3OczOY)

## 典型的なワークフロー##typical-workflow

Triggers の使用を準備するには、以下のステップに従います。

1. [イベントで実行する Cloud Code スクリプトまたはモジュールの作成:](#set-up-cloud-code)イベントの発生時に実行するゲームロジックを定義します。
2. [リソースの状態を変更するイベントのスケジュール:](#schedule-an-event)イベントがいつ発生するかを定義します。
3. [イベントで Cloud Code モジュールエンドポイントを実行するトリガーの設定:](#configure-a-trigger)イベントの発生時にどの Cloud Code スクリプトまたはモジュールが実行されるかを定義します。
4. [結果の検証:](#validate-the-result)Cloud Code スクリプトまたはモジュールが実行されたことを確認します。

> **Note:**
>
> **ノート**: Triggers を、他のサービスで発行されたイベントとともに使用することもできます。詳細については、[イベント](./manage-events/events.md) セクションを参照してください。

## 前提条件##prerequisites

ステップでは、[Unity Dashboard で Unity Gaming Services プロジェクト](/cloud/projects/create-project.md) がすでに作成済みであると見なします。

最初に、必要なアクセスロールでサービスアカウントを作成し、[UGS CLI](https://services.docs.unity.com/guides/ugs-cli/latest/general/get-started/install-the-cli/) を設定する必要があります。

### サービスアカウントを使用した認証##authenticate-using-a-service-account

Scheduling および Triggers サービスを呼び出す前に、サービスアカウントを使用して認証する必要があります。

1. [Unity Dashboard](https://cloud.unity.com) に移動します。
2. **Administration** (管理) > **Service Accounts** (サービスアカウント) を選択します。
3. **New** (新規) ボタンを選択し、サービスアカウントの名前と説明を入力します。
4. **Create** (作成) を選択します。

製品ロールを追加し、キーを作成します。

1. **Manage product roles** (製品ロールの管理) を選択します。
2. 以下のロールをサービスアカウントに追加します。
   * LiveOps ドロップダウンから、**Triggers Configuration Editor** (Triggers 設定編集者)、**Triggers Configuration Viewer** (Triggers 設定閲覧者)、**Scheduler Configuration Editor** (Scheduler 設定編集者)、**Scheduler Configuration Viewer** (Scheduler 設定閲覧者)、**Leaderboards Admin** (Leaderboards 管理者) を選択します。
   * Admin (管理者) ドロップダウンから **Unity Environments Viewer** (Unity 環境閲覧者) を選択します。
3. **Save** (保存) を選択します。
4. **Add Key** (キーの追加) を選択します。
5. base64 エンコードを使用して **Key ID** (キー ID) と **Secret key** (秘密鍵) をエンコードします。形式は "key\_id:secret\_key" です。この値をメモしておきます。

詳細については、[Authentication](/triggers/authentication.md) を参照してください。

### UGS CLI の設定##configure-the-ugs-cli

以下のステップに従って、UGS CLI の使用を準備します。

1. [UGS CLI をインストール](https://services.docs.unity.com/guides/ugs-cli/latest/general/get-started/install-the-cli/) します。

2. プロジェクト ID と環境を以下のように設定します。
   `ugs config set project-id <your-project-id>`
   `ugs config set environment-name <your-environment-name>`

3. 前に作成したサービスアカウントを使用して認証します。[認証の取得](https://services.docs.unity.com/guides/ugs-cli/latest/general/get-started/get-authenticated/) を参照してください。

### Leaderboards の設定##set-up-leaderboards

このサンプルに従うには、リーダーボードを作成する必要があります。

UGS CLI を使用して、以下の `leaderboard.lb` ファイルをデプロイできます。リーダーボードを昇順のソート順で定義し、ベストスコアを保持します。

`new-file` コマンドを実行して、リーダーボード設定をローカルに作成します。

```bash
ugs leaderboards new-file leaderboard
```

ファイル名はリーダーボード ID に対応します。以下の設定で `leaderboard.lb` ファイルを更新します。

```json
{
  "$schema": "https://ugs-config-schemas.unity3d.com/v1/leaderboards.schema.json",
  "SortOrder": "asc",
  "UpdateType": "keepBest",
  "Name": "leaderboard"
}
```

UGS CLI ツールを使用してファイルをデプロイします。

```bash
ugs deploy leaderboard.lb
```

リーダーボードを作成したので、そこにスコアを追加できます。

### 任意: リーダーボードへのスコアの追加##optional:-add-scores-to-the-leaderboard

以下の Cloud Code スクリプトを実行して、[Unity Dashboard](https://cloud.unity.com) からリーダーボードにスコアを追加できます。すべてのテスト実行でプレイヤー ID トークンを再生成して、新しいプレイヤーのスコアを生成してください。

#### JavaScript##javascript

```javascript
const { LeaderboardsApi } = require("@unity-services/leaderboards-1.1");
const _ = require("lodash-4.17");

module.exports = async ({ params, context, logger }) => {

  const leaderboardsApi = new LeaderboardsApi({ accessToken: context.accessToken });
  const leaderboardID = "leaderboard";

  var randomScore = _.random(1, 100);
  try {
    await leaderboardsApi.addLeaderboardPlayerScore(context.projectId, leaderboardID, context.playerId, { score: randomScore });

  } catch (err) {
    logger.error("Failed to add score to the leaderboard", { "error.message": err.message });
  }
};
```

## Cloud Code の設定##set-up-cloud-code

Triggers を使用するには、Cloud Code モジュールまたは Cloud Code スクリプトを定義する必要があります。モジュールまたはスクリプトはトリガー発生時に実行されます。以下のサンプルは、[Leaderboards](/leaderboards.md) と [Cloud Save](/cloud-save.md) を Cloud Code と統合して、リーダーボードの上位 5 人のプレイヤーにシーズントロフィーを授与します。

### Cloud Code C# モジュール##cloud-code-c-module

文字列引数 `key` および `value` を受け取る関数を使用して `SchedulerHelloWorld` モジュールを定義します。

モジュールエンドポイント `RewardPlayers` は、リーダーボードから上位 5 人のプレイヤーを取得し、各プレイヤーの 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;
using Unity.Services.Leaderboards.Model;

namespace SchedulerHelloWorld;

public class SchedulerHelloWorld
{
    private const string LeaderboardId = "leaderboard";
    private readonly ILogger<SchedulerHelloWorld> _logger;
    public SchedulerHelloWorld(ILogger<SchedulerHelloWorld> logger)
    {
        _logger = logger;
    }

    [CloudCodeFunction("RewardPlayers")]
    public async Task RewardPlayers(IExecutionContext ctx, IGameApiClient gameApiClient, string key, string value)
    {
        var top5Players = await GetTop5(ctx, gameApiClient);
        foreach (var score in top5Players)
        {
            try
            {
                var response = await gameApiClient.CloudSaveData.SetItemAsync(ctx, ctx.ServiceToken, ctx.ProjectId, score.PlayerId, new SetItemBody(key, value));
                _logger.LogInformation("Data saved successfully");
            }
            catch (ApiException e)
            {
                _logger.LogError( "Failed to record data for playerId {playerId}. Error: {Error}", score.PlayerId, e.Message);
                throw new Exception($"Failed to record data for playerId {score.PlayerId}. Error: {e.Message}");
            }
        }
    }

    [CloudCodeFunction("GetTopPlayers")]
    public async Task<List<LeaderboardEntry>> GetTop5(IExecutionContext ctx, IGameApiClient gameApiClient)
    {
        try
        {
            var results = await gameApiClient.Leaderboards.GetLeaderboardScoresAsync(ctx, ctx.ServiceToken, new Guid(ctx.ProjectId),
                LeaderboardId, null, 5);
            return results.Data.Results;

        }
        catch (ApiException e)
        {
            _logger.LogError(e, "Failed to get top players for leaderboard: {LeaderboardId}. Error: {Error}", LeaderboardId, e.Message);
            throw new Exception($"Failed to get top players for leaderboard: {LeaderboardId}. Error: {e.Message}");
        }
    }

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

}
```

モジュールをデプロイします。

モジュールのデプロイ方法を学習するには、[Hello World のデプロイ](/cloud-code/modules/getting-started.md#deploy-the-module) を参照してください。

> **Note:**
>
> **ノート:** UGS CLI を使用してモジュールをデプロイする場合は、`Cloud Code Editor` の追加のサービスアカウントロールを忘れずに追加してください。

### Cloud Code JavaScript スクリプト##cloud-code-javascript-script

Cloud Code スクリプトを作成することで、同じ結果を実現できます。

必要な文字列引数 `key` および `value` を使用して `SchedulerHelloWorld` スクリプトを作成します。

#### JavaScript##javascript

```javascript
const { DataApi } = require("@unity-services/cloud-save-1.4");
const { LeaderboardsApi } = require("@unity-services/leaderboards-1.1");


module.exports = async ({ params, context, logger }) => {
  // Get top 5 players from the Leaderboard
  const leaderboardId = "my-leaderboard";
  const leaderboardsApi = new LeaderboardsApi(context);
  const cloudSaveApi = new DataApi(context);

  let result;

  try {
    result = await leaderboardsApi.getLeaderboardScores(context.projectId, leaderboardId, 0, 5);
  } catch (err) {
    logger.error("Failed to retrieve players from the leaderboard", { "error.message": err.message });
    throw err;
  }

  // Set Cloud Save data for every player
  const promises = result.data.results.map(async (score) => {
    try {

      await cloudSaveApi.setItem(context.projectId, score.playerId, {
        key: params.key,
        value: params.value,
      });

    } catch (err) {
      logger.error("Failed to update Cloud Save data", { "error.message": err.message }, { "affectedPlayerId": score.playerId });
      return;
    }
  });

  await Promise.all(promises);
};
```

スクリプトを公開します。

スクリプトのデプロイ方法を学習するには、[Hello World のデプロイ](/cloud-code/scripts/getting-started.md#deploying-hello-world) を参照してください。

> **Note:**
>
> **ノート:** UGS CLI を使用してスクリプトをデプロイする場合は、追加のサービスアカウントロール (`Cloud Code Script Publisher` と `Cloud Code Editor`) を忘れずに追加してください。

## イベントのスケジュール##schedule-an-event

Cloud Code スクリプトまたはモジュールを定義した後で、上位 5 人のプレイヤーがいつトロフィーを授与されるかを決定するスケジュールを作成できます。

以下のサンプルでは、プレイヤーにシーズントロフィーを授与する 1 回限りのスケジュールを定義します。

`new-file` コマンドを実行して、スケジュール設定をローカルに作成します。

```bash
ugs scheduler new-file schedule-config
```

以下の設定で `schedule-config.sched` ファイルを更新します。

```json
{
  "$schema": "https://ugs-config-schemas.unity3d.com/v1/schedules.schema.json",
  "Configs": {
    "grant-trophy": {
      "EventName": "trophy-for-top-5",
      "Type": "one-time",
      "Schedule": "2024-08-28T00:00:00Z",
      "PayloadVersion": 1,
      "Payload": "{\"key\": \"seasonal-trophy\", \"value\": \"2024-08-28\"}"
    }
  }
}
```

イベントの `payload` は、Cloud Code スクリプトまたはモジュールに渡される Cloud Code パラメーターを搬送します。`schedule` フィールドを変更して、イベントがトリガーされる日時を変更します。

UGS CLI ツールを使用して設定をデプロイします。

```bash
ugs deploy schedule-config.sched
```

以下のようなレスポンスが返されます。

```text
Deployed:
    schedule-config.sched
```

これで、特定の時刻にイベントをトリガーするスケジュールが設定されました。ただし、イベントはまだ Cloud Code スクリプトまたはモジュールに接続されていません。

## トリガーの設定##configure-a-trigger

Cloud Code リソースをスケジュールに接続するには、トリガーを作成します。トリガーは、イベントが発生したとき、例えばスケジュールがトリガーされたときに Cloud Code モジュールまたはスクリプトを実行します。

`new-file` コマンドを実行して、トリガー設定をローカルに作成します。

```bash
ugs triggers new-file triggers-config
```

Cloud Code モジュールを作成した場合は、以下の設定で `triggers-config.tr` ファイルを更新します。

```json
{
  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",
  "Configs": [
    {
      "Name": "trophy-reward",
      "EventType": "com.unity.services.scheduler.trophy-for-top-5.v1",
      "ActionUrn": "urn:ugs:cloud-code:SchedulerHelloWorld/RewardPlayers",
      "ActionType": "cloud-code"
    }
  ]
}
```

Cloud Code スクリプトを作成した場合は、以下の設定で `triggers-config.tr` ファイルを更新します。

```json
{
  "$schema": "https://ugs-config-schemas.unity3d.com/v1/triggers.schema.json",
  "Configs": [
    {
      "Name": "trophy-reward",
      "EventType": "com.unity.services.scheduler.trophy-for-top-5.v1",
      "ActionUrn": "urn:ugs:cloud-code:SchedulerHelloWorld",
      "ActionType": "cloud-code"
    }
  ]
}
```

UGS CLI ツールを使用して設定をデプロイします。

```bash
ugs deploy triggers-config.tr
```

以下のようなレスポンスが返されます。

```text
Deployed:
    triggers-config.tr
```

これで、イベントの発生時に Cloud Code スクリプトまたはモジュールを実行するトリガーが設定されました。

## 結果の検証##validate-the-result

結果を検証するために、イベント発生の前後に上位プレイヤーを調べることができます。

1. [Unity Dashboard](https://cloud.unity.com) に移動します。
2. **Products** (製品) > **Leaderboards** を選択します。
3. **Overview** (概要) セクションを選択します。
4. `leaderboard` リーダーボードを選択します。
5. **Entries** (エントリー) タブを選択します。
6. 上位プレイヤー ID の 1 つを書き留めます。

プレイヤーデータが更新されたことを検証するために、プレイヤーの Cloud Save データを確認できます。

1. [Unity Dashboard](https://cloud.unity.com) から、**Products** (製品) > **Player Management** を選択します。
2. 検索フィールドで、前に書き留めておいたプレイヤー ID を入力し、**Find player** (プレイヤーを検索) を選択します。
3. **Cloud Save** > **Data** (データ) セクションに移動します。
4. `seasonal-trophy` キーと値 `2023-08-28` が表示されています。

Cloud Code ログを調べて、Cloud Code スクリプトまたはモジュールが実行されたことを確認します。

1. [Unity Dashboard](https://cloud.unity.com) で **Cloud Code** を開きます。
2. **Logs** (ログ) を選択します。

**Logs** (ログ) ページに、`SchedulerHelloWorld` モジュールまたはスクリプトからのログエントリーが表示されます。