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

> Server-Sent Events (SSE) ベースの Events API を使用して、任意のタイミングで Auth0 からイベントを取得します。

# Events API でイベントを取り込む

Events API は、Event Streams に代わるプル型の手段です。Auth0 が送信先にイベントをプッシュする代わりに、アプリケーションが `GET /api/v2/events` への長時間維持する接続を開き、Server-Sent Events (SSE) ストリームとしてイベントを受け取ります。いつ接続するか、切断後にどのように再開するか、どのくらいの速度でイベントを取り込むかは、すべてアプリケーション側で制御できます。

このアプローチは、次のような場合に役立ちます。

* webhook エンドポイントを用意せずに、自分のペースでイベントを処理したい。
* バックフィルや復旧のために、特定の時点からイベントを再生したい。
* プッシュ型の配信よりもポーリングを好むシステムと統合したい。

<div id="how-the-events-api-works">
  ## Events API の仕組み
</div>

アプリケーションが Events API に接続すると、SSE メッセージのストリームを受信します。各メッセージには、**オフセット** として機能する `id` フィールドが含まれます。接続が切断された場合、アプリケーションは再接続し、最後に受信した オフセット を渡します。Auth0 はその位置から配信を再開するため、イベントが失われることはありません。

SSE ストリームには、次のメッセージタイプが含まれます。

| Message type                                      | Purpose                                                         |
| ------------------------------------------------- | --------------------------------------------------------------- |
| `:connected`                                      | 接続が確立されたことを示します。これはデータイベントではなく、SSE のコメントです。                     |
| `retry: <ms>`                                     | 切断後に再接続するまで、どれくらい待機するかを SSE クライアントに伝えます。                        |
| `event: <type>` (for example, `user.created`)     | `data` フィールドに完全な ペイロード を含む実際のイベントです。                            |
| `event: offset-only`                              | 一定間隔 (ハートビート の頻度) で送信される進行マーカーです。イベントデータを配信せずに オフセット を更新します。    |
| `:` followed by text (for example, `: heartbeat`) | プロキシやロードバランサーがアイドル状態の接続を閉じないようにするための keep-alive コメントです。対応は不要です。 |
| `event: error`                                    | 終端エラーです。このメッセージの後、ストリームは閉じます。                                   |

<div id="example-sse-stream">
  ### SSEストリームの例
</div>

```text wrap lines theme={null}
:connected

retry: 2000

event: user.created
id: MTIzNDIzNDEzCg==
data: {"offset":"MTIzNDIzNDEzCg==","event":{"id":"evt_abc123","type":"user.created","time":"2025-06-01T12:00:00Z","data":{"object":{"user_id":"auth0|123","email":"jane@example.com"}}}}

event: offset-only
id: 4LcuTXmVDASuNRQt
data: {"offset":"4LcuTXmVDASuNRQt"}

: heartbeat

event: user.updated
id: NTY3ODkwMTIzCg==
data: {"offset":"NTY3ODkwMTIzCg==","event":{"id":"evt_def456","type":"user.updated","time":"2025-06-01T12:05:00Z","data":{"object":{"user_id":"auth0|123","email":"jane.doe@example.com"}}}}
```

<div id="prerequisites">
  ## 前提条件
</div>

始める前に、以下を用意してください。

* Events が有効化されている Auth0 テナント。利用可能な Event Stream 接続数は、ご利用のプランによって異なります。

  | プラン          | 接続上限 |
  | ------------ | ---- |
  | Free         | 1    |
  | Self-service | 4    |
  | Enterprise   | 8    |

* `read:events` スコープを持つ Management API アクセストークン。詳しくは、[Management API Access Tokens](/docs/ja-jp/secure/tokens/access-tokens/management-api-access-tokens) をご覧ください。

<div id="connect-to-the-events-api">
  ## Events API に接続する
</div>

テナントの events エンドポイントへの SSE 接続を確立します。次の例では `curl` を使用します。

```bash wrap lines theme={null}
curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    "https://YOUR_DOMAIN/api/v2/events"
```

<div id="query-parameters">
  ### クエリパラメータ
</div>

クエリパラメータを使用して、ストリームを絞り込んだり、再開したりできます。

| Parameter        | Type   | Description                                                                                                                                        |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`           | string | 以前の `id` フィールドで返されたオフセットです。このオフセットの直後から配信が再開されます。                                                                                                  |
| `from_timestamp` | string | ISO 8601 形式のタイムスタンプです。この時刻以降に発生したイベントを返します。`from` とは同時に使用できません。初期設定や、既知の時点からイベントを再生する場合に最適です。継続的に受信する場合は、オフセットのほうがより正確なため、`from` を使って再開することを推奨します。 |
| `event_type`     | string | 含めるイベントタイプです。種類ごとにこのパラメータを繰り返して指定します (例: `event_type=user.created&event_type=user.updated`) 。                                                      |

```bash wrap lines theme={null}
curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    "https://YOUR_DOMAIN/api/v2/events?event_type=user.created&event_type=user.updated&from_timestamp=2025-06-01T00:00:00Z"
```

<div id="resume-after-a-disconnection">
  ## 切断後の再開
</div>

SSE 接続は、ネットワークの問題、トークンの有効期限切れ、サーバー側での接続の切り替え (Auth0 では負荷分散のため、通常は数分ごとに定期的に接続を閉じます) など、さまざまな理由で切断されることがあります。標準的な SSE クライアントライブラリは、再接続時に最後のオフセットを送信することで、こうした切断を透過的に処理します。

再接続時にオフセットを指定する方法は 2 つあります。

* **`Last-Event-ID` ヘッダー** — 標準的な SSE の再接続メカニズムです。ほとんどの SSE クライアントライブラリは、再接続時にこのヘッダーを自動的に設定します。
* **`from` query parameter** — クライアントが `Last-Event-ID` ヘッダーをサポートしていない場合は、こちらを使用します。

両方が指定されている場合は、`Last-Event-ID` ヘッダーが優先されます。

```bash wrap lines theme={null}
curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    -H "Last-Event-ID: MTIzNDIzNDEzCg==" \
    "https://YOUR_DOMAIN/api/v2/events"
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  すべてのメッセージ (`offset-only` メッセージを含む) の最新の `id` 値を永続ストレージに保存してください。アプリケーションが再起動した場合は、保存したオフセットを使って中断した箇所から配信を再開します。
</Callout>

<div id="handle-message-types">
  ## メッセージの種類を処理
</div>

<div id="real-events">
  ### 実際のイベント
</div>

`event` フィールドが既知のイベントタイプ (たとえば `user.created`) に一致するメッセージには、`data` フィールドにイベントの完全なペイロードが含まれます。JSON を解析し、ビジネスロジックに従ってイベントを処理してください。

<div id="offset-only-messages">
  ### オフセットのみのメッセージ
</div>

Auth0 は、ストリーム内の位置を進めるために、一定間隔 (ハートビートの頻度) で `offset-only` メッセージを送信します。これらのメッセージにはイベント `ペイロード` は含まれません。受信したら保存しているオフセットを更新してください。そうすることで、今後再接続した際に、すでに通過したイベントが再送されるのを防げます。

<div id="error-messages">
  ### エラーメッセージ
</div>

`event: error` メッセージは、オフセットの有効期限切れやサーバー側の問題など、回復不能な問題を示します。このメッセージを受信すると、ストリームは終了します。アプリケーションではエラーを記録したうえで、適切なオフセットまたは新しい `from_timestamp` を指定して再接続する必要があります。

<div id="heartbeats">
  ### ハートビート
</div>

`:` で始まる行は、ハートビート用のSSEコメントです。これにより、プロキシやロードバランサーを経由しても接続を維持できます。特別な処理は必要ありません。

<div id="server-side-connection-cycling">
  ## サーバー側での接続の切り替え
</div>

Auth0 では、負荷分散のために SSE 接続を定期的に切断します (通常は数分ごと) 。これは想定された動作であり、エラーではありません。標準的な SSE クライアントライブラリ (`eventsource` npm パッケージを含む) は、`Last-Event-ID` ヘッダーを使って自動的に再接続するため、アプリケーションはイベントを取りこぼすことなく正しいオフセットから再開できます。

カスタムの SSE クライアントを実装する場合は、最新のオフセットを保持し、その値を使って再接続することで、接続の切断に適切に対応できるようにしてください。

<div id="implement-a-consumer">
  ## コンシューマーを実装する
</div>

以下の Node.js の例では、イベントを処理し、オフセットをファイルに保存する最小限の Events API コンシューマーを示しています。

```javascript wrap lines theme={null}
const EventSource = require("eventsource");
const fs = require("fs");

const OFFSET_FILE = "./offset.txt";
const AUTH0_DOMAIN = "YOUR_DOMAIN";
const TOKEN = "YOUR_MANAGEMENT_API_TOKEN";

function loadOffset() {
    try {
        return fs.readFileSync(OFFSET_FILE, "utf8").trim();
    } catch {
        return null;
    }
}

function saveOffset(offset) {
    fs.writeFileSync(OFFSET_FILE, offset);
}

function connect() {
    const offset = loadOffset();
    const params = new URLSearchParams();
    params.append("event_type", "user.created");
    params.append("event_type", "user.updated");
    params.append("event_type", "user.deleted");

    if (offset) {
        params.append("from", offset);
    }

    const url = `https://${AUTH0_DOMAIN}/api/v2/events?${params.toString()}`;

    const es = new EventSource(url, {
        headers: {
            "Authorization": `Bearer ${TOKEN}`
        }
    });

    // 実際のイベントを処理する
    for (const type of ["user.created", "user.updated", "user.deleted"]) {
        es.addEventListener(type, (msg) => {
            const payload = JSON.parse(msg.data);
            console.log(`Received ${type}:`, payload.event.id);

            // ここでイベントを処理する

            saveOffset(msg.lastEventId);
        });
    }

    // オフセットのみの進捗マーカーを処理する
    es.addEventListener("offset-only", (msg) => {
        saveOffset(msg.lastEventId);
    });

    // 終端エラーを処理する
    es.addEventListener("error", (msg) => {
        if (msg.data) {
            const errorPayload = JSON.parse(msg.data);
            console.error("Stream error:", errorPayload.error);
        }
        es.close();

        // 一定時間後に再接続する
        setTimeout(connect, 5000);
    });
}

connect();
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `eventsource` npm パッケージは SSE プロトコルを実装しており、`Last-Event-ID` ヘッダーを使って自動的に再接続します。別の SSE ライブラリを使用する場合は、自動再接続とオフセットの引き継ぎに対応していることを確認してください。
</Callout>

<div id="error-responses">
  ## エラーレスポンス
</div>

接続を確立できない場合、Events API は標準的な HTTP ステータスコードを返します。

| ステータスコード | 意味                                                           |
| -------- | ------------------------------------------------------------ |
| `200`    | 接続が確立されました。イベントのストリーミングが開始されます。                              |
| `400`    | 無効なリクエストです。オフセット の値の形式が正しくないか、要求されたイベントタイプはサポートされていません。      |
| `401`    | アクセストークンがないか、無効です。                                           |
| `403`    | アクセストークンに `read:events` スコープが含まれていません。                       |
| `410`    | オフセット の有効期限が切れています。特定の時点から再開するには、`from_timestamp` の値を使用します。  |
| `429`    | レート制限を超過しています。`Retry-After` ヘッダーの値で指定された時間だけ待ってから、再試行してください。 |

<div id="learn-more">
  ## 詳細
</div>

* [イベントカタログ](/docs/ja-jp/events)
* [イベントストリームを作成する](/docs/ja-jp/customize/events/create-an-event-stream)
* [イベントのベストプラクティス](/docs/ja-jp/customize/events/events-best-practices)
* [Management API Access Tokens](/docs/ja-jp/secure/tokens/access-tokens/management-api-access-tokens)