印刷用ドキュメント - DRM サービスTOP

MediaProtect API Specification
Version 1.0.0
株式会社アールティーブイ
ソリューション事業部
Copyright © 2006 RTV Corporation. All rights reserved.
■ 改版履歴
日付
改訂内容
改訂者名
2006/11/06
初版(Version1.0.0)
RTV Solutions
Division Staff
-1-
1. 概要 ························································· 4
1.1.
ご契約 ................................................................................... 4
1.2.
コンテンツの保護 ................................................................. 4
1.3.
シリアルコードの発行 .......................................................... 5
1.4.
コンテンツの配置 ................................................................. 5
1.5.
再生の許可 ............................................................................ 6
2. 共通仕様 ··················································· 6
2.1.
フロー ................................................................................... 6
2.2.
サーバ及び基本URIについて................................................ 6
2.3.
使用可能な通信プロトコルの種類 ........................................ 6
2.4.
環境 - OSについて................................................................ 7
2.5.
環境 - プログラム言語について........................................... 7
2.6.
文字コードはUTF-8 を使用してください............................. 7
2.7.
例外処理................................................................................ 8
2.8.
戻り値の共通規則 ................................................................. 8
3. API仕様 ··················································· 8
3.1.
ExpirationLengthFromInitialPlay (ELFIP) ....................... 8
3.1.1.
URI ................................................................................................. 8
3.1.2.
CreateSerialCode Method.............................................................. 9
3.1.3.
RegisterSerialCode Method ......................................................... 10
4. Samples ················································· 12
4.1.
ExpirationLengthFromInitialPlay (ELFIP) ..................... 12
-2-
4.1.1.
C# / .NET Framework 2.0.............................................. 12
4.1.2.
PHP 5 ............................................................................. 15
4.1.3.
その他の言語................................................................... 17
-3-
1. 概要
RTV MediaProtect Service (以降、当サービスと呼びます) について簡単に紹介し、またその主
要機能である MediaProtect API の説明とサンプルコードを提供します。
当サービスそのものの詳細な情報は当社ウェブサイトの DRM サービスに関する説明
http://drm.atrtv.com/
をご覧ください。
当サービスご利用にあたってお客様にご理解いただく必要のある基本的な流れは以下の通りで
す。
1.1. ご契約
利用にはまず当サービス利用契約を結ぶ必要があります。ご契約いただきますと、当サービスを
ご利用いただくためのお客様専用の ID とパスワードを発行いたします。当社提供のツール類お
よび API 利用時にこの ID とパスワードが必要になります。
1.2. コンテンツの保護
当社提供の専用ツールでお客様のお持ちのメディアファイルを保護します。保護対象のメディア
の形式は WMA および WMV です。それ以外の形式の場合は、 Microsoft 社 が提供している
ツール等を利用して、当サービスが保護できる形式に変換する必要があります。また、保護対象
のファイルサイズは 2 GBytes が上限となっております。
専用ツールは当社の DRM 用サーバにお客様のメディアファイルの内容を一度転送します。そし
て Windows Media Rights Manager の機能により保護化を行います。保護化と同時に、保護
したコンテンツに関する情報を当社のサーバが保持し、後述するシリアルコードの発行およびラ
イセンスの発行に備えます。そして最後に「保護済みメディアファイル」をお客様のお手元にお
送りします。
-4-
お客様はこの工程で取得した「保護済みメディアファイル」を配布してください。当サービス
ではこの「保護済みメディアファイル」を保護します。元となったファイル自体は変更されず、
また保護もされませんので配布せずに封印してください。
「保護済みメディアファイル」の送付と同時に、当サービスでのそのファイルの識別用データで
ある「コンテンツ ID」も併せて送付します。シリアルコード発行の際にはこれを利用して、シ
リアルコード発行対象を指定することができますので、なくさないようお願いいたします。
「保護済みメディアファイル」が本当に保護されているかどうかを確認するには、実際に再生を
試みるのが最も簡単な方法です。シリアルコードの入力が要求され、何を入れても再生に失敗す
るはずです(シリアルコードを発行していませんから)。再生するには、後述の API を使用してシ
リアルコードを発行し、再生時にシリアルコードを入力してください。
1.3. シリアルコードの発行
後述する API をご利用頂くことで、保護したコンテンツを再生するためのシリアルコードを発
行することができます。本書ではこのシリアルコード発行用の API について説明いたします。
1.4. コンテンツの配置
保護済みのコンテンツの配置、配布はお客様が自由に選び、行うことができます。当サービスで
はコンテンツのコピーは一切制限しませんし、配布作業も行いません。
Windows Media ストリーミングサーバ、Web サーバからの配布(IIS や Apache など)、FTP サ
ーバからの配布、CD-ROM や DVD-ROM 等での配布、P2P アプリケーション(BitTorrent、Winny
など)を利用した配布など、任意の方法でコンテンツを配布することが可能です。当サービスで
は、配布方法を問わず、コンテンツを保護します。P2P を使用したからといって保護できなく
なるなどということはありません。
Windows Media ストリーミングサーバおよび Web サーバ、FTP サーバからの配信に関しまし
ては、当社でもサービスを提供いたしております。宜しければ当サービスと併せてご検討頂けた
ら幸いです。
当社の専用サーバ事業に関しましては http://atrtv.com/ 及び http://server.atrtv.com/ に詳し
く紹介させて頂いております。
-5-
1.5. 再生の許可
「保護済みメディアファイル」を入手した視聴者は、Windows Media Player で再生を試みるこ
とができます。保護されていないメディアファイルと違い、保護済みメディアファイルを再生す
るには、当サービスで発行したシリアルコードの入力を求められます。正しくシリアルコードを
入力し、そのシリアルコードが当サービスサーバ上で現在有効であることが確認された場合にの
み、視聴者の Windows Media Player に再生用の鍵のような情報が転送され、その鍵に書かれ
た規則に従ってのみ再生できるようになります。
2. 共通仕様
シリアルコード発行用 API の各 API の説明に入る前に、各 API 共通の仕様について説明いたし
ます。
2.1. フロー
フローは実に単純になっています。お客様側から API を実行しますと、結果が返ります。これ
だけです。
2.2. サーバ及び基本 URI について
当ドキュメント(Lite 版)では非公開です。
2.3. 使用可能な通信プロトコルの種類
SOAP 1.1, SOAP 1.2, HTTP POST, HTTP GET に対応しています。また、当サービスではす
べての通信に SSL を使用していますので、
クライアントとして当社サーバに SSL 通信(Port443)
を行う環境も必要になります(お客様のシステムがサーバとして SSL 通信のホストとなる必要は
ありません、当社サーバへのクライアントとしての接続にのみ必要になります)。
廉価なレンタルサーバなどでは、希に SSL 通信が使用できない(機能を提供していない)という
事例があることを確認しております。ご契約の前にご利用のレンタルサーバ会社に SSL の使用
の可否を確認されることをおすすめいたします。OS やプログラム言語のバージョンがあまりに
-6-
古い場合や、一般的な追加コンポーネントのインストールを怠っている場合などの環境では、上
記のような場合があります。当社ではセキュリティの関係上、SSL を使用しない API を提供す
る予定はありません。
2.4. 環境 - OS について
上記通信プロトコルに対応してさえいれば、OS は問いません。当社では現在、Windows
XP(SP2)、Windows Server 2003(SP1)、Fedora Code 5 での動作確認を行っています。
2.5. 環境 - プログラム言語について
前述した通信プロトコルに対応してさえいれば、プログラム言語は問いません。SOAP の実体
は単なるテキストデータに過ぎないため、原理的には XML や SOAP のライブラリがなくとも
実装は可能ですが、もし安定した実装の SOAP ライブラリがあれば、それを利用するのが賢明
でしょう。
当社では
・ C# / Microsoft .NET Framework / Windows XP SP2, Windows Server 2003
・ PHP5 / Fedora Core 5 (Linux)
で動作確認を行っています。
未確認ではありますが、以下の言語でも実装が容易であると思われます。
・ Java
・ Perl
・ ASP
・ PHP4
この件に関し、実装の確認が行えましたら公表いたします。また、新たな環境による実装につい
てのお客様からのフィードバックを歓迎いたします。
2.6. 文字コードは UTF-8 を使用してください
当システムとの通信に使用する文字列の文字コードには、UTF-8 を使用してください。お使い
の処理系・開発環境・実行環境が UTF-8 以外の文字コードで動作している場合、一度 UTF-8
に変換してからでないと当サービスは利用できません。また、UTF-8 以外の文字コードを使用
した場合の動作は保証いたしません。
-7-
2.7. 例外処理
各 API の引数名や引数の数に誤りがある場合、SOAP の例外が返ります。また API の URI に
誤りがある場合、誤り方によって様々な HTTP のレスポンスが発生します。これらをどのよう
な形で受信できるかは処理系によって異なりますので、事前にエラーの返り方を実際にプログラ
ムを作って確認されることをおすすめいたします。基本的に、本ドキュメントで紹介した以外の
URI を使用した場合の動作は保証できません。本ドキュメントで紹介した以外の URI は使用し
ないでください。
2.8. 戻り値の共通規則
各 API の結果はすべて「object 型データの一次元配列」の形式で返ります。配列の１つめは必
ず整数値が入り、エラーコードが格納されます。エラーコードの意味、および配列のその他の内
容については API によって異なりますので、後述する各 API の説明をお読みください。
3. API 仕様
3.1. ExpirationLengthFromInitialPlay (ELFIP)
ELFIP を利用してシリアルコードを発行すると、視聴者がそのシリアルコードを利用してメデ
ィアファイルの再生を試みる場合、そのシリアルコードの初回利用時の情報を当サービスが保持
し、初回利用時から一定期間だけ視聴できるように視聴者による再生を許可します。初回利用時
からの再生許可期間は、シリアルコード発行機能で指定できます。
3.1.1. URI
URI は当ドキュメントでは非公開です、ご契約後にお渡しします。
API の URI は、ドキュメントも兼ねておりますのでブラウザで閲覧および動作確認を行うこと
もできます。ブラウザからの「テスト」機能は単なるデモではなく、実際に利用可能なシリア
ルコードを発行できてしまいますのでその点ご留意ください。
-8-
3.1.2. CreateSerialCode Method
指定したコンテンツを再生するためのシリアルコードを発行します。引数に誤りがなければ、シ
リアルコードが発行されます。
3.1.2.1. 引数
引数名称
型
備考
contentProviderID
string
お客様ご契約時のコンテンツプロバ
イダ ID を設定してください。
contentProviderPassword
string
お客様のコンテンツプロバイダパス
ワードを設定してください。
contentID
string
シリアルコード発行対象メディアフ
ァイルのコンテンツ ID を設定してく
ださい。
expireDays
int
シリアルコード初回利用時からの再
生許可期間を日単位で指定してくだ
さい。1 日=24 時間で計算します。0
を指定した場合は無期限になります。
最大は 24584(約 67 年)までです。それ
より大きい値を入力した場合の動作
は不定です。
3.1.2.2. 戻り値
序列
名称
型
1
エラーコード
int
2
シリアルコード
string
備考
16 桁の英数字。エラー発生時は不定。
-9-
3.1.2.3 エラーコード
コード
備考
0
成功
1
未定義のエラー
2
contentProviderID か contentProviderPassword のどちらかあるいは両方に
誤りがある
3
存在しない contentID を指定している
4
expireDays の指定に誤りがある
3.1.3. RegisterSerialCode Method
指定したコンテンツを再生するためのシリアルコードを登録します。指定したシリアルコードが
すでに使用されている場合や、当サービスが規定するシリアルコードの生成規則に反する場合
は、登録に失敗することがあります。生成規則は規則が改正される毎に公開いたします。
3.1.3.1. 引数
引数名称
型
備考
contentProviderID
string
お客様ご契約時のコンテンツプロバ
イダ ID を設定してください。
contentProviderPassword
string
お客様のコンテンツプロバイダパス
ワードを設定してください。
contentID
string
シリアルコード発行対象メディアフ
ァイルのコンテンツ ID を設定してく
ださい。
serialCode
string
登録したいシリアルコードを設定し
てください。
expireDays
int
シリアルコード初回利用時からの再
生許可期間を日単位で指定してくだ
さい。1 日=24 時間で計算します。0
を指定した場合は無期限になります。
最大は 24584(約 67 年)までです。それ
より大きい値を入力した場合の動作
- 10 -
は不定です。
3.1.3.2. 戻り値
序列
名称
型
1
エラーコード
int
備考
3.1.3.3. エラーコード
コード
備考
0
成功
1
未定義のエラー
2
contentProviderID か contentProviderPassword のどちらかあるいは両方に
誤りがある
3
存在しない contentID を指定している
4
expireDays の指定に誤りがある
5
指定した serialCode は既にこの contentID のために使用されている
6
指定した serialCode は当サービスのシリアルコード管理機能が許可しなかっ
たため、少なくともこの contentID と組み合わせて使用することができない
- 11 -
4. Samples
利用サンプルを API 別に掲載しました。
4.1. ExpirationLengthFromInitialPlay (ELFIP)
ELFIP を使用するサンプルを紹介します。引数等はお客様ご自身のものと置き換えないと動作
しません。
4.1.1. C# / .NET Framework 2.0
C#言語に関する以下のサンプルの作成には、Visual Studio 2005 を使用しています。「.NET
Framework 2.0」でのみ動作確認しています。「.NET Framework 1.1」からの利用も未確認で
すが容易であると思われます。
- 12 -
using System;
using System.Collections.Generic;
using System.Text;
// 1. 「ソリューションエクスプローラ」から
// 「参照設定」を右クリックして「Web参照を追加」
// WSDLのURI(当ドキュメントでは非公開)
// を指定します。
// 2. usingディレクティブで、追加したnamespaceを指定すると作業が容易になります。
using MediaProtect_Sample.com.atrtv.drm1;
namespace MediaProtect_Sample
{
class Program
{
static void Main(string[] args)
{
// 3. ELFIPオブジェクトを生成します。
ExpirationLengthFromInitialPlaySerialCodeManager scm
= new ExpirationLengthFromInitialPlaySerialCodeManager();
// 4. 当サンプルでは、CreateSerialCode を実行します。
object[] ret =
scm.CreateSerialCode(
"契約時にご提供するコンテンツプロバイダIDを設定してください",
"コンテンツプロバイダパスワードを設定してください",
"コンテンツIDを指定してください",
1
/* 初回再生許可時からいつまで再生を許可するかを日単位で指定してください */ );
// 5. 戻り値はオブジェクトの配列になっています。1つめがエラーコードです。
if (ret[0] == 0)
{ // エラーコード0 の場合は成功です。返値の配列の2つめがシリアルコードです。
Console.WriteLine("成功しました。生成したシリアルコード: {0}", ret[1]);
}
else
- 13 -
{ // 失敗した場合、詳細をエラーコードから知ることができます。
Console.WriteLine("失敗しました。エラーコード: {0}", ret[0]);
}
}
}
}
- 14 -
4.1.2. PHP 5
Fedora Core 5 に標準添付されている PHP5 で動作試験を行ったサンプルプログラムです。
お客様の環境に応じて書き換えてご利用ください。
// 当プログラムをコマンドラインから使用する場合は、
// 大抵の Unix 環境では↓のような記述が必要になります。
// Web に配置している場合は不要になる場合もあります。
// お客様ご使用の環境に関するお問い合わせにはお答えできません。
#!/usr/bin/php
<?php
// 当プログラムを Web に配置する場合は、↓の１行を有効にしてください。
// また不要な改行を取り除くなど、環境に合わせた修正を行ってください。
// お客様ご使用の環境に関するお問い合わせにはお答えできません。
// echo "Content-type: text/plain\n\n";
//
// 使用する機能の WSDL を取得します。
$client = new SoapClient(
'WSDL の URI を指定してください',
array('trace' => TRUE)
);
//
// 引数を準備します
$params = array(
'contentProviderID' => '契約時にご提供するコンテンツプロバイダ ID を設定してください',
'contentProviderPassword' => 'コンテンツプロバイダパスワードを設定してください',
'contentID' => 'コンテンツ ID を指定してください',
'expireDays' => '3' // 初回再生許可時からいつまで再生を許可するかを日単位で指定してください
- 15 -
);
//
// 当サンプルでは、CreateSerialCode を実行します。
$fault = FALSE;
try
{
$resultObj = $client->__soapCall('CreateSerialCode', array('parameters' => $params));
}
catch(SoapFault $exception)
{ // 引数などに誤りがある場合は例外が返ります。
$fault = TRUE;
echo "*** Fault ***\r\n\r\n"; print_r($exception); echo "\r\n\r\n";
}
//
// 以下のプログラムコードは、成功時に結果を echo で表示しています。
// 改造して適宜ご利用ください。
if(! $fault)
{
echo "*** Result ***\r\n\r\n"; print_r($resultObj->CreateSerialCodeResult); echo "\r\n\r\n";
foreach( $resultObj->CreateSerialCodeResult as $key => $tmp )
{
echo "[$key => $tmp]\n";
if( is_array( $tmp ) )
{
foreach( $tmp as $k2 => $t2 )
{
echo "
[[ $k2 => $t2 ]]\n";
}
}
}
echo "\n";
}
//
- 16 -
// 以下のプログラムコードは、通信内容を、送信時のものと受信時のものとに分けて
// すべて表示します。
// 動作確認やログ取得用などに、改造して適宜ご利用ください。
echo
"***
Request
***\r\n\r\n"
.
/*
htmlspecialchars(
*/
rtrim($client->__getLastRequestHeaders()) . "\r\n\r\n" . $client->__getLastRequest() /* ,
ENT_QUOTES) */ . "\r\n\r\n";
echo
"***
Response
***\r\n\r\n"
.
/*
htmlspecialchars(
*/
rtrim($client->__getLastResponseHeaders()) . "\r\n\r\n" . $client->__getLastResponse() /* ,
ENT_QUOTES) */ . "\r\n\r\n";
?>
4.1.3. その他の言語
その他の言語につきましては、当社での調査が行われ次第、本ドキュメントへの記載を追加した
いと考えております。もしお客様が本ドキュメントへ記載されている例以外の環境・言語への実
装に成功した場合、当社へのフィードバックを歓迎いたします。
- 17 -