Documentation Powered by ReDoc

ULIZA IP Broadcaster (Cloud) API 仕様書 (1.6.1)

本書は ULIZA IP Broadcaster (Cloud) が提供する API 仕様について記述しています。ULIZA IP Broadcaster (Cloud) の機能や管理画面の操作方法については ULIZA IP Broadcaster (Cloud) ユーザーガイド を参照してください。

なお、本書に掲載しているコードサンプル（Request samples）は、具体的な実装例を示すことで開発者を支援することを目的としていますが、掲載しているコードがすべての環境において正常に動作することを保証するものではありません。また、コードサンプル内で使用している関数やライブラリの安全性に関して、弊社は何ら責任を負うものではありません。

注意

本書に記述している API を利用するには、対応するオプション（「ULIZA EVENT STREAM - マルチ WebAPI オプション」など）のご契約が必要となります。詳細については お問い合わせ ください。

CHANGELOG

バージョン 改版日 改版内容
v1.0.0 2020/10/19 初版
v1.1.0 2021/6/7
  1. ライブイベントの ingestUrl 属性に domainRtmpUrl （RTMP 送出先 URL）を追加
  2. ライブイベントの属性に domainName （ライブ配信サーバーのサブドメイン名）を追加
v1.2.0 2021/7/14
  1. レポート取得 API を追加
  2. キャッシュクリア API を追加
v1.3.0 2021/10/27
  1. ライブイベント更新 API を追加
  2. ライブイベント終了 API のリクエストボディに pause (一時停止) を追加
  3. ライブイベントの属性に prioritizeInputPrimary (冗長化設定) を追加
  4. ライブイベントの ingestUrl 属性に domainPrimaryRtmpUrl （プライマリ RTMP 送出先 URL）と domainBackupRtmpUrl （バックアップ RTMP 送出先 URL）を追加
v1.3.1 2022/1/31 ライブイベントのラベルとカテゴリに関する説明を追加
v1.4.0 2022/6/1
  1. ライブイベントの属性に dvr (DVR設定) を追加
  2. ライブイベントの stream[].id 属性を必須から任意パラメーターに変更
v1.5.0 2023/1/10 ライブイベントの streamStatus 属性に ip (ライブエンコーダーの IP アドレス) と ua (ライブエンコーダーのユーザーエージェント)、source (採用されている入力) を追加
v1.6.0 2023/3/20
  1. ライブイベントの属性に enableTranscode (トランスコード機能) を追加
  2. ingestUrl の domainRtmpUrl (RTMP 送出先 URL) と rtmpUrl (RTMP 送出先 URL) の説明を更新
  3. ライブイベント終了 API のレスポンスボディに id (ライブイベントID) と paused (一時停止されたライブイベント) を追加
v1.6.1 2023/11/27
  1. ライブイベントの属性に archived (アーカイブ処理のステータス) を追加
  2. ライブイベントの属性に archivedat (アーカイブ完了日時) を追加

Authentication

特に断りのない限り、本書に記載されている全ての API に対するリクエストの Authorization ヘッダに下記の形式で有効な API 認証キーを含める必要があります。API 認証キーの取得方法については ULIZA プロダクトアカウントユーザーガイド を参照してください。リクエストに有効な API 認証キーが含まれていない場合は、401 Unauthorized が返却されます。

Authorization: Bearer <api-credential>

Live

ライブイベント管理系 API について以下に記述します。

ライブイベント一覧取得 API

ライブイベントに関する情報を取得します。

  • リクエスト送信者が ライブイベントの取得 権限を持っていない場合は、403 Forbidden が返却されます。

Responses

Response Schema: application/json
Array of objects

Request samples 

curl \
  -H 'Authorization: Bearer <your-token>' \
  'https://ipb-api.p.uliza.jp/v1/live'

Response samples

Content type
application/json
{
  • "data": [
    ]
}

ライブイベント作成 API

ライブイベントを作成します。

  • リクエスト送信者が ライブイベントの登録 権限を持っていない場合は、403 Forbidden が返却されます。
Request Body schema: application/json
name
required
string <= 200 characters

ライブイベントの名前

description
string <= 5000 characters

ライブイベントの説明

dvr
boolean

DVRの有無

archive
required
string
Enum: "same" "another" "none"

アーカイブ処理の種類

  • same ： ライブコンテンツに上書き登録
  • another ： ライブコンテンツと別コンテンツとして登録
  • none ： 登録しない
enableTranscode
boolean
Default: false

トランスコード機能の有効/無効

required
Array of objects [ 1 .. 3 ] items

ストリーム情報

segmentDuration
number >= 1
Default: 4

HLSセグメント秒数

prioritizeInputPrimary
boolean
Default: false

入力冗長化構成が行われたライブ配信での、接続や切断時の振る舞い。プライマリーとバックアップの両方が入力されている場合はプライマリーを配信します。

category
required
string <uuid>

ULIZA VMS (Cloud) に登録するカテゴリーID。カテゴリの取得についてはULIZA VMS (Cloud) API 仕様書を参照ください。

labels
Array of strings <uuid> unique

ULIZA VMS (Cloud) に登録するラベルID。ラベルの取得についてはULIZA VMS (Cloud) API 仕様書を参照ください。

Responses

Response Schema: application/json
id
string

ライブイベントID

object

作成したライブイベント

Request samples

Content type
application/json
{
  • "name": "ライブイベント1",
  • "description": "ライブイベントの説明です。",
  • "dvr": true,
  • "archive": "same",
  • "enableTranscode": true,
  • "streams": [
    ],
  • "segmentDuration": 6,
  • "prioritizeInputPrimary": true,
  • "category": "11111111-1111-1111-1111-111111111111",
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "11111111-1111-1111-1111-111111111111",
  • "item": {
    }
}

ライブイベント取得 API

ライブイベントに関する情報を取得します。

  • リクエスト送信者が ライブイベントの取得 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
live_id
required
string <UUID>

ライブイベント ID

Responses

Response Schema: application/json
object

ライブイベント

Request samples 

curl \
  -H 'Authorization: Bearer <your-token>' \
  'https://ipb-api.p.uliza.jp/v1/live'

Response samples

Content type
application/json
{
  • "data": {
    }
}

ライブイベント更新 API

ライブイベントを更新します。リクエストボディに含めなかったパラメーターは更新されません。

  • 指定したライブイベントの status が created 以外の場合は、400 BadRequest が返却されます。
  • リクエスト送信者が ライブイベントの更新 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
live_id
required
string <UUID>

ライブイベント ID

Request Body schema: application/json
name
string <= 200 characters

ライブイベントの名前

description
string <= 5000 characters

ライブイベントの説明

dvr
boolean

DVRの有無

archive
string
Enum: "same" "another" "none"

アーカイブ処理の種類

  • same ： ライブコンテンツに上書き登録
  • another ： ライブコンテンツと別コンテンツとして登録
  • none ： 登録しない
enableTranscode
boolean
Default: false

トランスコード機能の有効/無効

Array of objects [ 1 .. 3 ] items

ストリーム情報

segmentDuration
number >= 1
Default: 4

HLSセグメント秒数

prioritizeInputPrimary
boolean
Default: false

入力冗長化構成が行われたライブ配信での、接続や切断時の振る舞い。プライマリーとバックアップの両方が入力されている場合はプライマリーを配信します。

category
string <uuid>

ULIZA VMS (Cloud) に登録するカテゴリーID。カテゴリの取得についてはULIZA VMS (Cloud) API 仕様書を参照ください。

labels
Array of strings <uuid> unique

ULIZA VMS (Cloud) に登録するラベルID。ラベルの取得についてはULIZA VMS (Cloud) API 仕様書を参照ください。

Responses

Response Schema: application/json
id
string

ライブイベントID

object

更新したライブイベント

Request samples

Content type
application/json
{
  • "name": "ライブイベント1",
  • "description": "ライブイベントの説明です。",
  • "dvr": true,
  • "archive": "same",
  • "enableTranscode": true,
  • "streams": [
    ],
  • "segmentDuration": 6,
  • "prioritizeInputPrimary": true,
  • "category": "11111111-1111-1111-1111-111111111111",
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "11111111-1111-1111-1111-111111111111",
  • "item": {
    }
}

ライブイベント削除 API

指定したライブイベントを削除します。

  • 指定したライブイベントの status が created 以外の場合は、400 BadRequest が返却されます。
  • リクエスト送信者が ライブイベントの削除 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
live_id
required
string <UUID>

ライブイベント ID

Responses

Request samples 

curl \
  -X DELETE \
  -H 'Authorization: Bearer <your-token>' \
  'https://ipb-api.p.uliza.jp/v1/live/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Response samples

Content type
application/json
{
  • "code": "INVALID_REQUEST",
  • "message": "Bad request"
}

ライブイベント開始 API

指定したライブイベントの開始指示をします。ライブイベントが実行中になるまでには数分かかる場合があります。

  • 指定したライブイベントの status が created 以外の場合は、400 BadRequest が返却されます。
  • リクエスト送信者が ライブイベントの開始 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
live_id
required
string <UUID>

ライブイベント ID

Responses

Request samples 

curl \
  -H 'Authorization: Bearer <your-token>' \
  -d '@request.json' \
  'https://ipb-api.p.uliza.jp/v1/live/11111111-1111-1111-1111-111111111111/start'

Response samples

Content type
application/json
{
  • "code": "INVALID_REQUEST",
  • "message": "Bad request"
}

ライブイベント終了 API

指定したライブイベントを終了します。

  • 指定したライブイベントの status が started 以外の場合は、400 BadRequest が返却されます。
  • リクエスト送信者が ライブイベントの終了 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
live_id
required
string <UUID>

ライブイベント ID

Request Body schema: application/json
pause
boolean
Default: false

一時停止するかを示すフラグ。

Responses

Response Schema: application/json
id
string

ライブイベントID

object

一時停止されたライブイベント（一時停止のときのみ返却されます）

Request samples

Content type
application/json
{
  • "pause": true
}

Response samples

Content type
application/json
{
  • "id": "11111111-1111-1111-1111-111111111111",
  • "paused": {
    }
}

ライブイベントのキャッシュクリア API

指定したライブイベントのキャッシュの削除指示をします。キャッシュが完全に削除されるまでには数分かかる場合があります。

  • 指定したライブイベントの status が started 以外の場合は、400 BadRequest が返却されます。
  • リクエスト送信者が キャッシュクリア 権限を持っていない場合は、403 Forbidden が返却されます。
path Parameters
live_id
required
string <UUID>

ライブイベント ID

Responses

Request samples 

curl \
  -H 'Authorization: Bearer <your-token>' \
  -d '@request.json' \
  'https://ipb-api.p.uliza.jp/v1/live/11111111-1111-1111-1111-111111111111/clear'

Response samples

Content type
application/json
{
  • "code": "INVALID_REQUEST",
  • "message": "Bad request"
}

Report

レポート取得系 API について以下に記述します。

レポート取得 API

クエリパラメーター「start」「end」で指定した期間のライブイベントの一覧と統計情報を取得します。

  • 取得期間は 7 ヶ月未満になるように指定してください。7 ヶ月以上を指定した場合は、400 Bad Request が返却されます。
  • リクエスト送信者が auth:GET:accounts 権限を持っている場合は、サブアカウントを含むレポートを取得します。
  • リクエスト送信者が ライブイベントの取得 権限を持っていない場合は、403 Forbidden が返却されます。
query Parameters
start
required
string^[0-9]+$

レポート取得期間の開始日時(ミリ秒単位のUNIX時間)

end
required
string^[0-9]+$

レポート取得期間の終了日時(ミリ秒単位のUNIX時間)

Responses

Response Schema: application/json
object

Request samples 

curl \
  -H 'Authorization: Bearer <your-token>' \
  'https://ipb-api.p.uliza.jp/v1/report?start=1609426800000&end=1617202799999'

Response samples

Content type
application/json
{
  • "data": {
    }
}

Error Codes

すべてのエラーレスポンスにはエラーの種類を示すエラーコードが与えられます。返却されうるエラーコードの一覧とそれぞれの意味は下表の通りです。

エラーコード 原因となる操作 意味
INVALID_REQUEST すべての操作 不正なリクエスト形式
RESOURCE_NOT_FOUND すべての操作 指定したリソースが見つからない
RESOURCE_ALREADY_EXISTS すべての操作 指定したリソースが既に存在している
UNPROCESSABLE_STATUS すべての操作 そのライブイベントのステータスでは指定した操作ができない
OVER_SERVICE_LIMIT すべての操作 サービス利用制限を超過している
OVER_STORAGE_LIMIT ライブイベントの開始 ストレージの使用可能容量を超過している
REQUEST_UNAUTHORIZED すべての操作 認証エラーまたは認可されていないリクエスト
UNKNOWN_ERROR すべての操作 サーバ内部エラー