> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# カスタムプッシュソース API
> ソースを登録し、スコープが限定された API アクセスキーを使用して、JSON または CSV のイベントバッチを Living Security に送信します。
システムが、カタログコネクターによるポーリングではなく、Living Security へレコードを送信する場合は、カスタムプッシュソースを使用します。送信側は、JSON 配列または CSV ファイルをリージョンごとの HTTPS エンドポイントへ送信できます。
## 開始する前に
次のものが必要です。
* Living Security で連携およびアクセスキーを管理する権限
* HTTPS `POST` リクエストを実行できるサーバーサイドの送信側
* 組織の Living Security リージョン
* 固定のソース名と、1 つ以上のストリーム名
ソース名とストリーム名は、変更できないルーティングキーです。ソース名は、1～64 文字の小文字の英字、数字、またはハイフンで指定します。ストリーム名ではアンダースコアも使用できます。いずれも、先頭は英字または数字にする必要があります。
API アクセスキーは機密情報として扱ってください。ブラウザーのコードに記載したり、ソース管理にコミットしたり、サポートチケットで送信したりしないでください。
## 1. ソースとストリームを登録する
**設定 → 連携 → カタログ** に移動し、**Custom Push Source** を見つけて **追加** を選択します。
ソースのルーティングキーと、必要に応じて説明を入力します。たとえば、スペースを含む表示名ではなく `custom-phishing-sim` を使用します。
送信側が使用する各ストリームを追加します。最初のプッシュの前に、ソースとストリームの組み合わせが存在している必要があります。未登録の組み合わせでは `404 Not Found` が返されます。
作成後、**設定 → 連携 → 接続されました** でソースを開きます。**Push via API** ビューに、エンドポイントのパターンと最近の実行が表示されます。
## 2. プッシュ取り込みキーを作成する
**設定 → Access Keys** に移動し、**Create Access Key** を選択して、**Push Ingest** スコープを選択します。生成された値は一度しか表示されないため、すぐにコピーしてください。
このキーは 1 つの Living Security 組織に紐付けられます。プッシュリクエストに組織ヘッダーは不要です。ローテーションと失効については、[API アクセスキー](/ja/features/settings/api-keys)を参照してください。
## 3. リージョンのエンドポイントを選択する
Living Security 組織のホスト名を使用します。
| リージョン | ベース URL |
| - | - |
| 米国 | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| 欧州連合 | `https://api.eu-west-1.livingsecurity.ai/api/v1` |
`/push-ingest/{integrationKey}/{streamName}` を追加します。パスは大文字と小文字を区別し、登録済みのソースおよびストリームと完全に一致している必要があります。
登録済みのソース名。1～64 文字の小文字の英字、数字、またはハイフンを使用し、先頭は英字または数字にします。
登録済みのストリーム名。同じルールが適用され、アンダースコアも使用できます。
プッシュ取り込みアクセスキーを `Bearer ` として送信します。
JSON の場合は `application/json`、CSV の場合は `text/csv` を使用します。このヘッダーを省略した場合でも、サーバーは JSON 配列を検出できます。
任意の組織 UUID。組織はアクセスキーによってすでに決定されます。このヘッダーを送信する場合は、キーの組織と一致している必要があります。別の組織を選択することはできません。
### リクエスト本文
最上位の空でない JSON オブジェクト配列、またはヘッダー行を含む CSV ファイルのバイト列を送信します。名前付きの JSON ラッパーフィールドはありません。各バッチには、最大 10,000 件のレコード、かつ 10 MB までを含めることができます。
## 4. JSON バッチを送信する
要素がオブジェクトである、空でない JSON 配列を送信します。Living Security は本文が配列であればヘッダーがなくても検出できますが、`Content-Type: application/json` の指定を推奨します。また、多くの送信製品ではこれが必須です。
```bash JSON batch theme={null}
curl --request POST \
'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '[
{
"email": "person@example.com",
"event_at": "2026-09-21T14:30:00Z",
"action": "reported"
}
]'
```
```bash CSV file theme={null}
curl --request POST \
'https://api.us-east-1.livingsecurity.ai/api/v1/push-ingest/custom-phishing-sim/events' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: text/csv' \
--data-binary '@events.csv'
```
リクエストが成功すると `202 Accepted` が返されます。エラータブには、JSON 本文の形式が正しくない場合の `400 Bad Request` が表示されます。
```json 202 Accepted theme={null}
{
"runId": "01a0c45f-ae40-7e5f-8a9b-0c1d2e3f4a5b",
"recordsAccepted": 1,
"integrationKey": "custom-phishing-sim",
"streamName": "events"
}
```
```json 400 Invalid JSON theme={null}
{
"statusCode": 400,
"timestamp": "2026-09-22T14:30:00.000Z",
"path": "/api/v1/push-ingest/custom-phishing-sim/events",
"message": "Request body is not valid JSON. Send a JSON array of objects, or set Content-Type: text/csv to push a CSV.",
"error": "Bad Request"
}
```
受理は、バッチが非同期処理のために保存されたことを意味します。すべてのレコードがすでにアクティビティとして解釈されたことを意味するものではありません。
`400` の例では、JSON を修正するか、`Content-Type: text/csv` を指定して CSV を送信してから、再試行してください。
受理されたこのバッチの実行 ID。処理状況の確認に使用するため、保管しておいてください。
受理され、保存されたレコード数。
このプッシュで使用されたソース名。
このプッシュで使用されたストリーム名。
## 代わりに CSV を送信する
`Content-Type: text/csv` を設定し、上記の **CSV file** リクエスト例に示すとおりにファイルのバイト列を送信します。最初の行がフィールド名になります。
ブール値のテキストはブール値に、通常の数値のテキストは数値になります。先頭がゼロの値、安全でない大きな整数、日付、その他のテキストは文字列のままです。空のセルの場合、そのフィールドは省略されます。形式が正しくない行、引用符の対応が取れていない行、および UTF-16 ファイルは拒否されます。
## リクエストの制限と再試行
| 項目 | 現在の値 |
| - | - |
| 最大レコード数 | 1 リクエストあたり 10,000 件 |
| 最大リクエスト本文サイズ | 10 MB |
| 組織ごとのリクエストレート | 60 秒あたり 600 リクエスト |
サイズの大きなエクスポートは、両方の制限を満たすバッチに分割してください。各レスポンスを待ち、返された `runId` を送信側のログに保持してください。
| レスポンス | 意味 | 送信側の対応 |
| - | - | - |
| `202` | バッチが受理されました | `runId` を記録します。すぐに再送信しないでください |
| `400` | 名前、JSON、CSV、レコード数、または本文が無効です | リクエストを修正します。変更せずに再試行しないでください |
| `401` | キーが指定されていない、期限切れ、失効済み、または無効です | キーを置き換え、Bearer ヘッダーを使用します |
| `403` | キーに必要なスコープがありません | **Push Ingest** スコープのキーを作成します |
| `404` | ソースまたはストリームが登録されていません | 正確な組み合わせを登録するか、URL を修正します |
| `413` | リクエスト本文が 10 MB を超えています | バッチを小さなリクエストに分割します |
| `429` | IP レベルの一時的なスロットリングです | `Retry-After` がある場合はそれに従い、待機してから再試行します |
| `503` | 組織のレートバケットまたはリミッターを利用できません | `Retry-After` の間待機してから、同じバッチを再送信します |
通常の認証済み組織の制限では `429` ではなく `503` が返されるため、Webhook の送信側は再試行可能なものとして扱います。`503` はバッチが保存される前に返されます。示された間隔の経過後に同じバッチを再送信しても、受理済みの実行が重複することはありません。
## データフローを確認する
カスタムプッシュソースを開き、**Push History** を確認します。ストリーム、レコード数、キーの帰属、および処理状況を確認してください。メンテナンスされているインタープリターがあるデータは、その後、ユーザーや正規化されたアクティビティになります。インタープリターがないデータは保存されたままで、アクティビティは生成されません。
プロバイダー固有のガイドがある場合は、そこに記載されている正確なフィールド名とペイロード構造を使用してください。`202` が成功しても、配信されたことが確認できるだけで、任意のスキーマが Living Security のアクティビティにマッピングされることを保証するものではありません。
## トラブルシューティングチェックリスト
* 正しいソースからエンドポイントをコピーし、ストリームのプレースホルダーを置き換えます。
* アクセスキーは `Authorization: Bearer …` として送信してください。`x-api-key` は受け付けられません。
* 本文が、単一のオブジェクトやレコードを包むエンベロープではなく、最上位の JSON 配列であることを確認します。
* ハイフン、アンダースコア、大文字と小文字を含め、ソースとストリームのスペルを確認します。
* レスポンスが失われたバッチを再送信する前に、**Push History** を確認します。
* [Living Security サポート](mailto:support@livingsecurity.com)に問い合わせる際は、組織、ソース、ストリーム、リクエスト時刻、可能であれば `runId`、およびレスポンスステータスを含めてください。アクセスキーやイベントペイロードは含めないでください。
## 関連項目
サポートされている Zscaler の Web ログフィードを、正確なソース、ストリーム、ヘッダー、JSON 構造で構成します。
スコープが限定された認証情報を作成、ローテーション、失効します。
解釈された連携アクティビティがシグナルをどのように支えるかを説明します。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.