チャンネル管理

お知らせ

このドキュメントは機械翻訳で作成された下書きであり、現在レビュー中です。機械翻訳の特性上、一部の内容が不正確であったり、韓国語の原文と異なる場合があります。より正確な情報については、韓国語のドキュメントをご参照ください。

チャンネル管理 API v3 リファレンスへ移動

バージョン別機能範囲のご案内

v3 新機能: Callback URL 設定、セキュリティ機能設定、リファラーベースのアクセス制御、プレイヤースキン連携などのチャンネル別独立設定エンドポイントは、v3 で新たに追加された機能です。
共通認証: すべてのバージョンの API は、クエリ文字列パラメーター(?access_token=)を使用した共通認証方式を採用しています。エラー判定基準に関する共通仕様は、API v3 マイグレーションガイドの主な変更事項セクションを参照してください。

チャンネルリスト照会

既存 (v1): GET /media/channel/index
変更後 (v3): GET /channels

変更事項

レスポンスデータ構造の変更: 返却されるデータの配列位置が、既存の result.items[] から data[] 構造に変更され、ページング処理のための pagination オブジェクトが追加されました。
フィルターおよびページネーションパラメーターの追加: v1 では order パラメーターのみをサポートしていましたが、v3 では kind、status、page、per_page パラメーターが追加されました。

リクエストパラメーターとレスポンスフィールドの詳細マッピング

リクエストクエリパラメーター

パラメーター	v1 サポート有無	v3 サポート有無	説明
`order`	サポート (`created_at`/`position` と `asc`/`desc` の組み合わせ、デフォルト値: `position_asc`)	サポート (v1 と同一の Enum 仕様を維持)	ソート基準
`kind`	非サポート	サポート	チャンネル種類のフィルタリング
`status`	非サポート	サポート	チャンネル有効化状態のフィルタリング (`0`: 無効、`1`: 有効)
`page`	非サポート	サポート	照会対象のページ番号
`per_page`	非サポート	サポート	ページあたりの出力データ件数

レスポンスフィールドマッピング

key、name、position フィールドは全バージョン共通で同一に維持されます。

フィールド	v1 構造 (`result.items[]`)	v3 構造 (`data[]`、`ApiVodChannel` オブジェクト)	参考
コンテンツカウント	`count_of_media_contents`	`count_of_contents`	名称の簡素化
有効状態	`status` (整数型、`1` の場合有効)	`status` (Boolean)	データ型の変更
チャンネル種類	レスポンス最上位属性として返却	レスポンス本文から分離	-
新規追加フィールド	-	`description`、Callback およびセキュリティ関連設定フィールド (`use_pingback`、`pingback_url` など)	付加フィールドの追加

チャンネルオブジェクト仕様

v3 レスポンス仕様の ApiVodChannel オブジェクトは、以下のような構造を持ちます。

{
  "key": "string",
  "name": "string",
  "description": "string",
  "use_pingback": true,
  "pingback_url": "string",
  "leave_pingback_url": "string",
  "play_callback_url": "string",
  "use_referer_check": 0,
  "referer_check_domains": "string",
  "referer_reject_domains": "string",
  "referer_empty_allow": true,
  "use_pc_download": true,
  "pc_download_callback_url": "string",
  "use_mobile_download": true,
  "mobile_download_callback_url": "string",
  "default": true,
  "is_shared": true,
  "is_encrypted": true,
  "disable_tvout": true,
  "count_of_contents": 0,
  "position": 0,
  "status": true,
  "created_at": "string",
  "updated_at": "string"
}

新規チャンネル生成

既存 (v1): POST /media/channel/create
変更後 (v3): POST /channels

変更事項

設定フィールドの分離: v1 生成 API に存在していた Pingback および再生制御関連のフィールドは、v3 生成仕様から削除されました。v3 では、チャンネル生成完了後に別途 Callback エンドポイントを通じて設定する必要があります。
非サポートフィールドへの転換: v1 の media_player_policy および progress_plugin フィールドは、v3 では代替フィールドなしに削除されました。
レスポンスデータ仕様の高度化: v1 では成功時に生成された固有キー情報 (result.key) のみを返却していましたが、v3 では HTTP 201 Created ステータスコードとともに、新規生成されたチャンネルオブジェクト全体を返却します。

リクエストボディとレスポンス構造の詳細

リクエストボディ

フィールド	データ型 (v1)	データ型 (v3)	必須有無	説明
`name`	String	String	必須	生成するチャンネル名 (最大 50 文字)
`is_shared`	Integer	Integer	オプション	チャンネル共有ポリシー設定 (`0`(デフォルト値): 非共有チャンネル、`1`: 共有チャンネル)
`is_encrypted`	Integer	Integer	オプション	チャンネルセキュリティポリシー設定 (`0`(デフォルト値): 一般チャンネル、`1`: 暗号化コンテンツ専用チャンネル)
`use_pingback`	Integer	-	-	v3 専用の Callback エンドポイントへ機能移管
`pingback_url`	String	-	-	v3 専用の Callback エンドポイントへ機能移管
`media_player_policy`	String	-	-	v3 でフィールド削除
`progress_plugin`	Integer	-	-	v3 でフィールド削除
`description`	-	String	オプション	チャンネル説明 (v3 新規追加)

レスポンス構造の対照

v1: 成功時には固有キー形式のみが返却され、レスポンスメッセージ内にスペルミス (sucessfully) が存在します。

{ "error": 0, "message": "sucessfully", "result": { "key": "key_string" } }

v3: 標準データ構造を返却します。

{ "data": ApiVodChannel object, "status": "ok" }

チャンネル情報照会

既存 (v1/v2): 非サポート (単一照会エンドポイントなし)
変更後 (v3): GET /channels/{channel_key}

レスポンス構造の詳細

レスポンス構造仕様

レスポンスフィールドはチャンネルリスト照会仕様と同一です。

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

チャンネル情報修正

既存 (v1/v2): 非サポート
変更後 (v3): PUT /channels/{channel_key}

リクエストボディとレスポンス構造の詳細

リクエストボディ

フィールド	データ型	必須有無	説明
`name`	String	必須	チャンネル名
`description`	String	オプション	チャンネル説明
`use_realtime`	Integer	オプション	リアルタイムストリーミング(HLS)使用有無 (`0`: 未使用、`1`: 使用)
`use_aes128`	Integer	オプション	AES-128 暗号化使用有無 (`0`: 未使用、`1`: 使用)

レスポンス構造仕様

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

チャンネル削除

既存 (v1): POST /media/channel/delete/{channel_key}
変更後 (v3): DELETE /channels/{channel_key}

変更事項

HTTP メソッドの転換: HTTP メソッドが POST から DELETE に変更されました。
レスポンス構造の単純化: 既存の成功返却仕様を簡素化し、削除処理が承認されたことを意味する空の配列構造 ("data": []) を返却します。

チャンネル別コンテンツリスト照会

既存 (v1): GET /media/channel/media_content
既存 (v2): GET /vod/channels/{media_package}/media-contents
変更後 (v3): GET /channels/{channel_key}/media-contents

変更事項

パスパラメーターへの転換: チャンネル識別子の伝達方式が、v1 のクエリ文字列構造から URL パスパラメーター構造に標準化されました。v2 ではパスパラメーター名として media_package を使用していましたが、v3 では channel_key に統一しました。
フィルターパラメーターの追加: v3 では、ソートおよびページング処理をはじめ、検索や状態フィルターなど豊富な条件付きクエリパラメーターが追加されました。

リクエストパラメーターとレスポンス構造の詳細

リクエストクエリパラメーター

order、page、per_page: 照会ソート方式およびページング制御
keyword、state、encryption、publish、content_type: 状態値および種類フィルター
exist_original、exist_subtitle: 原本ファイルおよび字幕の存在有無フィルター
start_date、end_date: 期間範囲検索フィルター

レスポンス構造の対照

{ "error": 0, "result": { "count": 10, "order": "position_asc", "per_page": 20, "items": { "item": [] } } }

{ "data": [{ "transcoding_files": [], "subtitles": [] }] }

{ "data": [ApiVodMediaContent object], "pagination": { "current_page": 1, "per_page": 10, "total": 100 } }

チャンネル内コンテンツ単一照会

既存 (v1): GET /media/channel/media_content/{upload_file_key}
変更後 (v3): 非サポート (下記 API 統合案内を参照)

API 統合案内

v3 では、チャンネル内コンテンツ単一照会 API が廃止されました。代わりに、同一のデータ範囲照会を保証する汎用コンテンツ管理単一照会機能である GET /media-contents/{upload_file_key} の形に統合されました。

チャンネル–コンテンツ連携

既存 (v1): POST /media/channel/attach/{upload_file_key}
変更後 (v3): POST /channels/{channel_key}/media-contents/{upload_file_key}/attach

識別子パラメーターマッピングに関する注意

v1 では、コンテンツ識別子 (upload_file_key) のみをアドレスパスに含め、対象チャンネルキー (channel_key) はリクエストボディに格納して送信していました。しかし v3 では、両方の識別子が URL パスパラメーターに順番に配置されます。

v1 の実装形態をもとに URL エンドポイントアドレスのみを機械的に置換した場合、パス上のチャンネルキーとコンテンツキーの情報が互いに入れ違って誤ってマッピングされ、意図と異なる連携が行われたり、連携に失敗(404 Not Found)したりする可能性があるため、パラメーターバインディングの順序を必ず検証する必要があります。

リクエストパラメーターの送信位置とレスポンス構造の詳細

リクエストパラメーター送信位置の対照

区分	v1	v3
`channel_key`	リクエストボディ	URL パスパラメーター (前方に配置)
`upload_file_key`	URL パスパラメーター	URL パスパラメーター (後方に配置)

レスポンス構造の対照

{ "error": 0, "message": "...", "result": { "media_content_key": "..." } }

{ "data": ApiVodMediaContentKey object, "status": "ok" }

チャンネル–コンテンツ連携解除

既存 (v1): POST /media/channel/detach/{upload_file_key}
変更後 (v3): DELETE /channels/{channel_key}/media-contents/{upload_file_key}/detach

変更事項

HTTP メソッドの転換: HTTP メソッドが POST から DELETE に変更されました。
パラメーター位置の変更: チャンネルキー (channel_key) 項目が、既存のリクエストボディ構造から URL パスパラメーターに変更されて含まれます。
レスポンスデータの定型化: 成功時にテキストレスポンス値の代わりに空の配列構造 ("data": []) を返却します。

チャンネル–プレイヤースキン連携

既存 (v1/v2): 非サポート
変更後 (v3): POST /channels/{channel_key}/player-skins/{skin_id}/attach

レスポンス構造の詳細

レスポンス構造仕様

{ 
  "data": ApiVodPlayerSkin object, 
  "status": "ok" 
}

チャンネル–プレイヤースキン連携解除

既存 (v1/v2): 非サポート
変更後 (v3): DELETE /channels/{channel_key}/player-skins

レスポンス構造の詳細

レスポンス構造仕様

{ 
  "data": [], 
  "status": "ok" 
}

Callback URL 設定 - コンテンツ追加/削除/再生

既存 (v1/v2): 非サポート
変更後 (v3): PUT /channels/{channel_key}/callback

新機能案内

既存の v1 生成 API の属性として一括処理されていた Pingback および再生制御関連の設定構造が、独立した API に分離されました。

リクエストボディとレスポンス構造の詳細

リクエストボディ

フィールド	データ型	必須有無	説明
`use_pingback`	Integer	必須	Callback 機能の有効化 (`0`: 無効化、`1`: 有効化)
`pingback_url`	String	オプション	コンテンツのチャンネル追加 Callback URL
`leave_pingback_url`	String	オプション	コンテンツのチャンネル削除 Callback URL
`play_callback_url`	String	オプション	Play Callback URL

レスポンス構造仕様

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

Callback URL 設定 - ダウンロード

既存 (v1/v2): 非サポート
変更後 (v3): PUT /channels/{channel_key}/download-callback

リクエストボディとレスポンス構造の詳細

リクエストボディ

フィールド	データ型	必須有無	説明
`use_pc_download`	Integer	必須	PC ダウンロード機能の有効化 (`0`: 無効化、`1`: 有効化)
`pc_download_callback_url`	String	オプション	PC ダウンロード Callback URL
`use_mobile_download`	Integer	必須	モバイルダウンロード機能の有効化 (`0`: 無効化、`1`: 有効化)
`mobile_download_callback_url`	String	オプション	モバイルダウンロード Callback URL

レスポンス構造仕様

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

外部ディスプレイ遮断

既存 (v1/v2): 非サポート
変更後 (v3): PUT /channels/{channel_key}/security

リクエストボディとレスポンス構造の詳細

リクエストボディ

フィールド	データ型	必須有無	説明
`disable_tvout`	Integer	必須	外部ディスプレイ遮断設定 (`0`: 遮断なし、`1`: 遮断)

レスポンス構造仕様

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

リファラーベースのアクセス制御

既存 (v1/v2): 非サポート
変更後 (v3): PUT /channels/{channel_key}/referer

リクエストボディとレスポンス構造の詳細

リクエストボディ

フィールド	データ型	必須有無	説明
`use_referer_check`	Integer	必須	リファラーアクセス制御ポリシー設定 (`1`: 特定ドメイン許可、`2`: 特定ドメイン遮断)
`referer_check_domains[]`	Array	オプション	再生を許可するドメインアドレスリスト
`referer_reject_domains[]`	Array	オプション	再生を遮断するドメインアドレスリスト
`referer_empty_allow`	Boolean	オプション	リファラー情報がないリクエストの遮断有無

レスポンス構造仕様

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

チャンネルリスト照会​

リクエストクエリパラメーター​

レスポンスフィールドマッピング​

チャンネルオブジェクト仕様​

新規チャンネル生成​

リクエストボディ​

レスポンス構造の対照​

チャンネル情報照会​

レスポンス構造仕様​

チャンネル情報修正​

リクエストボディ​

レスポンス構造仕様​

チャンネル削除​

チャンネル別コンテンツリスト照会​

リクエストクエリパラメーター​

レスポンス構造の対照​

チャンネル内コンテンツ単一照会​

チャンネル–コンテンツ連携​

リクエストパラメーター送信位置の対照​

レスポンス構造の対照​

チャンネル–コンテンツ連携解除​

チャンネル–プレイヤースキン連携​

レスポンス構造仕様​

チャンネル–プレイヤースキン連携解除​

レスポンス構造仕様​

Callback URL 設定 - コンテンツ追加/削除/再生​

リクエストボディ​

レスポンス構造仕様​

Callback URL 設定 - ダウンロード​

リクエストボディ​

レスポンス構造仕様​

外部ディスプレイ遮断​

リクエストボディ​

レスポンス構造仕様​

リファラーベースのアクセス制御​

リクエストボディ​

レスポンス構造仕様​

チャンネルリスト照会

リクエストクエリパラメーター

レスポンスフィールドマッピング

チャンネルオブジェクト仕様

新規チャンネル生成

リクエストボディ

レスポンス構造の対照

チャンネル情報照会

レスポンス構造仕様

チャンネル情報修正

リクエストボディ

レスポンス構造仕様

チャンネル削除

チャンネル別コンテンツリスト照会

リクエストクエリパラメーター

レスポンス構造の対照

チャンネル内コンテンツ単一照会

チャンネル–コンテンツ連携

リクエストパラメーター送信位置の対照

レスポンス構造の対照

チャンネル–コンテンツ連携解除

チャンネル–プレイヤースキン連携

レスポンス構造仕様

チャンネル–プレイヤースキン連携解除

レスポンス構造仕様

Callback URL 設定 - コンテンツ追加/削除/再生

リクエストボディ

レスポンス構造仕様

Callback URL 設定 - ダウンロード

リクエストボディ

レスポンス構造仕様

外部ディスプレイ遮断

リクエストボディ

レスポンス構造仕様

リファラーベースのアクセス制御

リクエストボディ

レスポンス構造仕様