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

# サンドボックスイベント

サンドボックスイベントは、主要なサンドボックスライフサイクル操作のクエリ可能なタイムラインを提供します。イベントは、トラブルシューティング、監査、利用状況分析、請求照合に使用できます。

## サンドボックスイベントをクエリする

events API を使用して、アカウントのサンドボックスイベントを一覧表示します。イベントは、サンドボックス、テンプレート、イベントタイプ、ステータス、時間範囲でフィルタリングできます。

### SDK を使用してイベントをクエリする

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox'

  const result = await Sandbox.getEvents({
    sandboxID: 'iq721h44siv24wmyrh5oc',
    events: ['create', 'pause', 'resume', 'connect', 'timeout', 'delete'],
    limit: 10,
    offset: 0,
  })

  console.log('Events:', result.items)

  if (result.hasMore) {
    const nextPage = await Sandbox.getEvents({
      sandboxID: 'iq721h44siv24wmyrh5oc',
      limit: 10,
      offset: 10,
    })

    console.log('Next page:', nextPage.items)
  }
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Sandbox

  result = Sandbox.get_events(
      sandbox_id="iq721h44siv24wmyrh5oc",
      events=["create", "pause", "resume", "connect", "timeout", "delete"],
      limit=10,
      offset=0,
  )

  print("Events:", result.items)

  if result.has_more:
      next_page = Sandbox.get_events(
          sandbox_id="iq721h44siv24wmyrh5oc",
          limit=10,
          offset=10,
      )

      print("Next page:", next_page.items)
  ```
</CodeGroup>

### サンドボックスインスタンスのイベントをクエリする

すでにサンドボックスインスタンスがある場合は、インスタンスレベルの events メソッドを使用して、そのサンドボックスのイベントをクエリします。

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox'

  const sandbox = await Sandbox.create()
  const result = await sandbox.getEvents({
    events: ['create', 'pause', 'resume', 'connect', 'timeout', 'delete'],
    limit: 10,
  })

  console.log(result.items)
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.core import Sandbox

  sandbox = Sandbox.create()
  result = sandbox.get_events(
      events=["create", "pause", "resume", "connect", "timeout", "delete"],
      limit=10,
  )

  print(result.items)
  ```
</CodeGroup>

## イベントをフィルタリングする

クエリパラメーターを使用して、イベントタイムラインを絞り込みます。

| オプション        | 型        | 必須  | デフォルト / 制限                 | 説明                                                                                          |
| ------------ | -------- | --- | -------------------------- | ------------------------------------------------------------------------------------------- |
| `startTime`  | `int64`  | いいえ | デフォルトは `endTime - 30 days` | Unix タイムスタンプ（秒）としてのクエリ開始時刻。範囲は両端を含みます。                                                      |
| `endTime`    | `int64`  | いいえ | デフォルトは現在時刻                 | Unix タイムスタンプ（秒）としてのクエリ終了時刻。`startTime` より大きい必要があります。                                        |
| `sandboxID`  | `string` | いいえ | -                          | サンドボックス ID でフィルタリングします。部分一致がサポートされています。                                                     |
| `templateID` | `string` | いいえ | -                          | テンプレート ID でフィルタリングします。部分一致がサポートされています。                                                      |
| `events`     | `string` | いいえ | デフォルトは主要イベントセット            | カンマ区切りのイベントタイプ。現在の主要イベントセットは `create`、`pause`、`resume`、`connect`、`timeout`、および `delete` です。 |
| `state`      | `string` | いいえ | -                          | `success` や失敗ステータスなど、イベントステータスでフィルタリングします。                                                  |
| `orderAsc`   | `bool`   | いいえ | `false`                    | イベントを `recordAt` の昇順で並べ替えます。デフォルトでは、イベントは降順で返されます。                                          |
| `offset`     | `int32`  | いいえ | デフォルト `0`、最小 `0`           | スキップするイベント数。                                                                                |
| `limit`      | `int32`  | いいえ | デフォルト `10`、最小 `1`、最大 `100` | 返すイベントの最大数。                                                                                 |

<Note>
  時刻フィールドは Unix タイムスタンプ（秒）を使用します。ミリ秒のタイムスタンプは渡さないでください。

  最大クエリ時間範囲は 60 日です。より長いタイムラインの場合は、リクエストを複数の小さな時間範囲に分割してください。
</Note>

## ページネーション

イベントはオフセットベースのページネーションを使用します。`offset: 0` から開始します。`hasMore` が `true` の場合、`offset + limit` で次のページをリクエストします。`limit` の最大値は 100 です。

## レスポンスフィールド

events レスポンスには、`items` 配列とページネーションメタデータが含まれます。

| フィールド     | 説明                          |
| --------- | --------------------------- |
| `items`   | クエリに一致するサンドボックスイベントの一覧。     |
| `total`   | ページネーション前に、クエリに一致するイベントの総数。 |
| `hasMore` | 現在のページの後にさらにイベントがあるかどうか。    |

`items` の各項目には、次のフィールドがあります。

| フィールド          | 説明                                                                     |
| -------------- | ---------------------------------------------------------------------- |
| `eventID`      | 一意のイベント ID。                                                            |
| `recordAt`     | Unix タイムスタンプ（秒）としてのイベント記録時刻。                                           |
| `templateID`   | サンドボックスで使用されるテンプレート ID。                                                |
| `templateName` | サンドボックスで使用されるテンプレート名。                                                  |
| `sandboxID`    | サンドボックス ID。                                                            |
| `eventName`    | `create`、`pause`、`resume`、`connect`、`timeout`、または `delete` などのイベントタイプ。 |
| `state`        | イベントステータス。                                                             |
| `errorMsg`     | イベントが失敗した、または例外が発生した場合のエラーメッセージ。エラーがない場合は通常空です。                        |
| `statusCode`   | 利用可能な場合、操作に関連付けられた HTTP ステータスコード。                                      |

## レスポンス例

```json theme={"system"}
{
  "items": [
    {
      "eventID": "evt_123",
      "recordAt": 1766650000,
      "templateID": "tmpl_abc",
      "templateName": "ubuntu-base",
      "sandboxID": "i3vrzzatkxojecvfuesnz",
      "eventName": "create",
      "state": "success",
      "errorMsg": "",
      "statusCode": 200
    }
  ],
  "total": 1,
  "hasMore": false
}
```