> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-fix-docs-5525.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HooksからActionsへの移行

> 既存のAuth0 HooksコードをAuth0 Actionsコードに移行する方法を学びます。

既存のHooksをActionsに変換する際には、その種類のフックに対応するトリガーを新しいアクションと関連付ける必要があります。提供するマッピングの識別に沿って以下の手順に従えば、ほぼ同一の機能性に保てるはずです。

## 移行を計画する

デプロイされたActionsはアクティブなHooksの後に実行されるため、Dashboardでフックを一度に1つずつ変換することも、<Tooltip data-tooltip-id="react-containers-DefinitionTooltip-0" href="/docs/ja-jp/glossary?term=management-api" tip="Management API: 顧客が管理タスクを実行できるようにするための製品。" cta="用語集の表示">Management API</Tooltip>を使用して一度にすべて変換することもできます。

コードを変換してから、アクションをアクティブにし、フックを非アクティブにする必要があります。アクションの有効化とフックの無効化は、連続してすばやく実行できますが、順序によっては、両方が実行されない、またはどちらも実行されない時間が短期間発生する場合があります。

このため、パイプラインを段階的に移行することをお勧めします。フックコードの一部をアクションコードに変換し、ステージング環境でテストしてから、一度に1つずつライブに移行します。アクティブなHooksはActionsのデプロイ前に作動するため、フック内のいくつかのロジックを構築した状態で維持しつつ、その他のロジックをActionsでテストできます。

<Card title="移行を計画するときのヒント">
  * フラグを使って、コストがかかる操作や1回限りの操作が重複しないようにします。
  * 変更は、影響やトラフィックが最も少ない時間帯や時期に行います。
  * 移行のスクリプトを作成し、一括または繰り返してテストと実装が行えるように、[Auth0 Deploy CLI](/docs/ja-jp/deploy-monitor/deploy-cli-tool)の使用を考慮します。
</Card>

## 制限事項を理解する

ActionsはHooksでできることの大部分を処理できますが、移行を開始する前にいくつかの制限事項に注意する必要があります（注：HooksとActionsはどちらも移行中に実行できます）。

* Actionsは、アクセストークンやAPI応答などのデータを複数の実行にわたって保持することはできません。
* Actionsには、Hooksのように[Management APIのアクセストークン](https://auth0.com/docs/customize/rules/use-management-api)や[グローバル`auth0`オブジェクト](https://auth0.com/docs/best-practices/rules-best-practices/rules-environment-best-practices#global-object)へのアクセスが提供されていません。

すべての制限事項については、「[Actionsの制限事項](/docs/ja-jp/customize/actions/limitations)」を参照してください。

## コードを変換する

フックをアクションに変換するには、フック固有のコードをActionsコードに置き換える必要があります。このセクションでは、機能するフックを同等のアクションに変換するためのタスクについて説明します。

<Card title="コードを変換するときのヒント">
  * 一般的に、Actionsの`event`オブジェクトについて、Hooks機能に渡されたオブジェクトの読み取り専用プロパティを確認します。
  * コードを書くときは、Auth0 DashboardのActions Code Editorを使います。エラーがハイライトされたり、オートコンプリート機能によって提案が自動入力されたりするので、便利です。
  * 稼働させる前に、[新しいActionsのテスト](/docs/ja-jp/customize/actions/test-actions)を[ステージング環境やテスト環境](/docs/ja-jp/get-started/auth0-overview/create-tenants/set-up-multiple-environments)で念入りに行います。
</Card>

### フックコードを新しいアクションにコピーする

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  フックのコードを新しいアクションにコピーし、Auth0 DashboardのActionsコードエディターで使用することをお勧めします。コードにある未解決の問題が特定できます。
</Callout>

1. 運用テナントにログインし、変換元となるフックのコードをコピーします。
2. 非運用テナントに切り替えて、[［Auth0 Dashboard］ > ［Actions（アクション）］ > ［Library（ライブラリ）］](https://manage.auth0.com/#/select-tenant?path=/actions/library)に移動します。
3. **［Build Custom（カスタムの構築）］** を選択した後、

   * 変換するフックの名前と一致するアクションの **Name（名前）** を入力します。
   * **［Trigger（トリガー）］** で、適切なトリガーを選択します **。**

     \| フックのタイプ | アクションのトリガー |
     \| --- | --- |
     \| Client Credentials Exchange（クライアント資格情報交換） | M2M/Client-Credentials（M2M/クライアント資格情報） |
     \| Pre-User-Registration（ユーザー登録前） | Pre User Registration（ユーザー登録前） |
     \| Post-User-Registration（ユーザー登録後） | Post User Registration（ユーザー登録後） |
     \| Post-Change-Password（パスワード変更後） | Post Change Password（パスワード変更後） |
     \| Send Phone Message（電話メッセージの送信） | Send Phone Message（電話メッセージの送信） |
   * **［Runtime（ランタイム）］** で、 **［Node 16］** を選択します。
   * **［Create（作成）］** を選択します。
4. Actionsコードエディターのコードブロックで、変換したいフックコードをエクスポートされた関数の下に貼り付けます。
5. コードを関数に移動するときに、この記事で後述している変更を加えます。Actionsの新しいトリガーに関連付けられた`event`オブジェクトについてもお読みください。このガイドの後半で「[データへのアクセス方法を変更する](#change-how-data-is-accessed)」セクションに移動すると、関連するドキュメントへのリンクが表示されます。

### 関数宣言を変更する

Hooksの関数はデフォルトのエクスポートを使ってエクスポートされますが、Actionsの関数は名前を付けてエクスポートされます。名前付きエクスポートは、変換するフックの種類によって変化します。マッピングには以下が含まれます。

| フックの種類                                    | 名前付きエクスポート                      |
| ----------------------------------------- | ------------------------------- |
| Client Credentials Exchange（クライアント資格情報交換） | `onExecuteCredentialsExchange`  |
| Pre-User Registration（ユーザー登録前）            | `onExecutePreUserRegistration`  |
| Post-User Registration（ユーザー登録後）           | `onExecutePostUserRegistration` |
| Post-Change Password（パスワード変更後）            | `onExecutePostChangePassword`   |
| Send Phone Message（電話メッセージ送信）             | `onExecuteSendPhoneMessage`     |

**変更前**

```javascript lines theme={null}
module.exports = async function myHooksFunction(){}
```

**変更後**

```javascript lines theme={null}
// Client Credentials Exchange
exports.onExecuteCredentialsExchange = async (event, api) => {}

// Pre-User Registration
exports.onExecutePreUserRegistration = async (event, api) => {}

// Post-User Registration
exports.onExecutePostUserRegistration = async (event) => {}

// Post-Change Password
exports.onExecutePostChangePassword = async (event) => {}

// Send Phone Message
exports.onExecuteSendPhoneMessage = async (event) => {}
```

### 依存関係を変換する

HooksとActionsは依存関係を類似した方法で処理します。どちらも、依存関係は、UIまたはManagement APIを使って個別に追加され、コードに含められます。どちらの場合も、`npm`レジストリで利用可能なパッケージを要求することができます。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `npm`モジュールが最新バージョンでないなら、今こそアップデートする絶好の機会です！
</Callout>

1. フックコード内の`require`ステートメントを検索してください。
2. バージョン番号を削除しますが、これらの番号はメモしておいてください。
3. 依存関係が[コアNodeJSモジュール](https://github.com/nodejs/node/tree/master/lib)でない場合は、「[初めてアクションを作成する](/docs/ja-jp/customize/actions/write-your-first-action)」の「依存関係を追加する」セクションの手順に従って依存関係を追加してください。依存関係がコアNodeJSモジュールである場合は、追加する必要はありません。
4. 見つけた`require`ステートメントを`function`宣言の外に移動してください。

### シークレットを変換する

HooksとActionsはシークレットを類似した方法で処理します。どちらも、シークレットは、UIまたはManagement APIを使ってフックやアクションごとに追加され、コードに含められます。

シークレットをHooksからActionsに変換するには、以下の手順で行います。

1. 操作中の特定のアクションに必要な値を保存します。
2. アクション内からアクセスする必要がある値ごとにシークレットを追加します。方法については、「[初めてアクションを作成する](/docs/ja-jp/customize/actions/write-your-first-action)」の「 **シークレットを追加する** 」セクションをお読みください。
3. コードを変換します。

**変更前**

```javascript lines theme={null}
async function (user, context, cb) {
    const { SECRET_NAME } = context.webtask.secrets;

    // ... additional code
}
```

**変更後**

```javascript lines theme={null}
async (event, api) => {
    const { SECRET_NAME } = event.secrets;

	// ... additional code
};
```

フックの場合と同様に、Auth0は保管時のすべてのシークレット値を暗号化します。

### データへのアクセス方法を変更する

フックでは、ユーザーやクライアン、要求についてのデータ、およびその他のコンテキストデータがフック関数に渡される複数の因数に保管されます。Actionsでは、このデータは再形成され、`event`オブジェクトに移動します。プロパティの多くはそのまま移行されましたが、わかりやすくするために一部が結合されました。

`event`オブジェクトは、変換するフックの種類によって変化します：

* [クライアント資格情報の交換 - Actionsイベントオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-event-object)
* [パスワード変更後- Actionsイベントオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger/post-change-password-event-object)
* [ユーザー登録後 - Actionsイベントオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger/post-user-registration-event-object)
* [ユーザー登録前 - Actionsイベントオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-event-object)
* [電話メッセージの送信 - Actionsイベントオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/mfa-notifications-trigger/send-phone-message-event-object)

**変更前**

```javascript lines theme={null}
async function (user, context, cb) {
	const clientId = context.clientID;
	const tenant = context.connection.tenant

	// ... additional code
}
```

**変更後**

```javascript lines theme={null}
async (event, api) => {
	const clientId = event.client.client_id;
	const tenant = event.tenant.id;

	// ... additional code
};
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  フックの`context`オブジェクトとは異なり、`event`オブジェクトのプロパティで保管・変更されたデータは、他のアクションでは使用できません。フックが、これらのプロパティでデータを設定することでコア機能をトリガーしている場合は、アクション間でデータを保持するために、[Machine to Machine（M2M）](/docs/ja-jp/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-api-object)や[Pre User Registration（ユーザー登録前）](/docs/ja-jp/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-api-object)のアクションフローにある`api`インターフェイスを使う必要があります。
</Callout>

### コールバックを変換する

フックの処理が終了したら、`callback()`関数を呼び出して、実行を完了する必要があります。それとは逆に、Actionsはコールバックのメカニズムを使用しないため、Actionsの関数から`callback()`のすべてのインスタンスを削除する必要があります。

`callback()`関数を使ってクライアント資格情報交換やユーザー登録前のフックで要求を失敗させたりユーザーを更新したりしていた場合でも、Actionsでは新しい`api`インターフェースを通じてこれを行うことができます。

#### Client Credentials Exchange（クライアント資格情報の交換）

Client Credentials Exchange Hook（クライアント資格情報の交換フック）でアクセストークンにクレームを追加する場合には以下を使用していました。

```javascript lines theme={null}
// Client Credentials Exchange Hook
module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope;

  access_token['https://example.com/claim'] = 'bar';
  cb(null, access_token);
};
```

Actionsの[クライアント資格情報交換のAPIオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-api-object)を使用できます：

```javascript lines theme={null}
// Client Credentials Exchange Action
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("https://example.com/claim", 'bar');  
};
```

#### Pre User Registration（ユーザー登録前）

Pre User Registration Hook（ユーザー登録前のフック）でアクセストークンにクレームを追加する場合には以下を使用していました。

```javascript lines theme={null}
// Pre User Registration Hook
module.exports = function (user, context, cb) {
	if (user.app_metadata.condition === "success") {
      var response = {};
      response.user = { user_metadata: { favorite_color: "purple" } };
      // This Hook succeeded, proceed with the next Hook.
	  return callback(null, response);
	}

	if (user.app_metadata.condition === "failure") {
		// This Hook failed, stop the login with an error response.
		return callback(new Error("Failure message"));
	}

	// ... additional code
};
```

[Pre User Registration（ユーザー登録前）のAPIオブジェクト](/docs/ja-jp/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-api-object)を使用できます：

```javascript lines theme={null}
// Pre User Registration Action
exports.onExecutePreUserRegistration = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// This Action succeeded, proceed with next Action.
		api.user.setUserMetadata("favorite_color", "purple");
		return;
	}

	if (event.user.app_metadata.condition === "failure") {
		// This Action failed, stop the call with an error response.
		return api.access.deny("Failure message");
	}

	// ... additional code
};
```

## 移行を完了する

新しいActionsコードを作成してテストしたら、アクションを有効にし、フックを無効にする必要があります。これらの2つのタスクは連続してすばやく実行できますが、順序によっては、両方が実行されない、またはどちらも実行されない時間が短期間発生する場合があります。アクティブなHooksはActionsのデプロイ前に作動するので、ルール内のいくつかのロジックを構築した状態で維持しつつ、その他のロジックをActionsでテストできます。