DRM サービスTOP > メディアプロテクト > APIの仕様について

@RTV
会社概要販売代理  
メディアプロテクトとは
メディアプロテクトの特徴
他社サービスとの比較
DRMについて
DRMの信頼性
オプション
メディアプロテクト料金
メディアプロテクトよくある質問
メディアプロテクト導入事例
メディアプロテクトお問い合わせ
メディアプロテクトお申し込み
DRMパッケージツール
APIの仕様について
DRM TOPページへ戻る




DRMサービス


@RTV ストリーミング配信サービス
ライブ配信

@RTV ストリーミング配信
ストリーミング配信


@RTV 会員制システムASP
会員制サイト

DRMパッケージツール詳細
印刷用ドキュメント

1.DRM-API 概要

@RTV DRM サービス「メディアプロテクト」 (以降、当サービスと呼びます) について簡単に紹介し、またその主要機能であるMediaProtect APIの説明とサンプルコードを提供します。

当サービスそのものの詳細な情報は当社ウェブサイトのDRMサービスに関する説明
http://drm.atrtv.com/
をご覧ください。

当サービスご利用にあたってお客様にご理解いただく必要のある基本的な流れは以下の通りです。

1.1. ご契約
利用にはまず当サービス利用契約を結ぶ必要があります。ご契約いただきますと、当サービスをご利用いただくためのお客様専用のIDとパスワードを発行いたします。当社提供のツール類およびAPI利用時にこのIDとパスワードが必要になります。

1.2. コンテンツの保護
当社提供の専用ツールでお客様のお持ちのメディアファイルを保護します。保護対象のメディアの形式は WMA および WMV です。それ以外の形式の場合は、 Microsoft社 が提供しているツール等を利用して、当サービスが保護できる形式に変換する必要があります。また、保護対象のファイルサイズは 2 GBytes が上限となっております。

専用ツールは当社のDRM用サーバにお客様のメディアファイルの内容を一度転送します。そして Windows Media Rights Manager の機能により保護化を行います。保護化と同時に、保護したコンテンツに関する情報を当社のサーバが保持し、後述するシリアルコードの発行およびライセンスの発行に備えます。そして最後に「保護済みメディアファイル」をお客様のお手元にお送りします。

お客様はこの工程で取得した「保護済みメディアファイル」を配布してください。当サービスではこの「保護済みメディアファイル」を保護します。元となったファイル自体は変更されず、また保護もされませんので配布せずに封印してください。

「保護済みメディアファイル」の送付と同時に、当サービスでのそのファイルの識別用データである「コンテンツ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/ に詳しく紹介させて頂いております。

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やプログラム言語のバージョンがあまりに古い場合や、一般的な追加コンポーネントのインストールを怠っている場合などの環境では、上記のような場合があります。当社ではセキュリティの関係上、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以外の文字コードを使用した場合の動作は保証いたしません。

2.7. 例外処理
各APIの引数名や引数の数に誤りがある場合、SOAPの例外が返ります。またAPIのURIに誤りがある場合、誤り方によって様々なHTTPのレスポンスが発生します。これらをどのような形で受信できるかは処理系によって異なりますので、事前にエラーの返り方を実際にプログラムを作って確認されることをおすすめいたします。基本的に、本ドキュメントで紹介した以外のURIを使用した場合の動作は保証できません。本ドキュメントで紹介した以外のURIは使用しないでください。

2.8. 戻り値の共通規則

各APIの結果はすべて「object型データの一次元配列」の形式で返ります。配列の1つめは必ず整数値が入り、エラーコードが格納されます。エラーコードの意味、および配列のその他の内容についてはAPIによって異なりますので、後述する各APIの説明をお読みください。

3.API仕様


3.1. ExpirationLengthFromInitialPlay (ELFIP)
ELFIPを利用してシリアルコードを発行すると、視聴者がそのシリアルコードを利用してメディアファイルの再生を試みる場合、そのシリアルコードの初回利用時の情報を当サービスが保持し、初回利用時から一定期間だけ視聴できるように視聴者による再生を許可します。初回利用時からの再生許可期間は、シリアルコード発行機能で指定できます。

3.1.1. URI
URIは当ドキュメントでは非公開です、ご契約後にお渡しします。

APIのURIは、ドキュメントも兼ねておりますのでブラウザで閲覧および動作確認を行うこともできます。ブラウザからの「テスト」機能は単なるデモではなく、実際に利用可能なシリアルコードを発行できてしまいますのでその点ご留意ください。
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桁の英数字。エラー発生時は不定。
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年)までです。それより大きい値を入力した場合の動作は不定です。
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 と組み合わせて使用することができない
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」からの利用も未確認ですが容易であると思われます。

using System;

using System.Collections.Generic;

using System.Text;

 

// 1. 「ソリューションエクスプローラ」から

// 「参照設定」を右クリックして「Web参照を追加」

// WSDLURI(当ドキュメントでは非公開)

// を指定します。

// 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

      { // 失敗した場合、詳細をエラーコードから知ることができます。

        Console.WriteLine("失敗しました。エラーコード: {0}", ret[0]);

      }

    }

  }

}

4.1.2. PHP 5
Fedora Core 5 に標準添付されている PHP5 で動作試験を行ったサンプルプログラムです。
お客様の環境に応じて書き換えてご利用ください。

// 当プログラムをコマンドラインから使用する場合は、

// 大抵のUnix環境では↓のような記述が必要になります。

// Webに配置している場合は不要になる場合もあります。

// お客様ご使用の環境に関するお問い合わせにはお答えできません。

#!/usr/bin/php

 

 

<?php

// 当プログラムをWebに配置する場合は、↓の1行を有効にしてください。

// また不要な改行を取り除くなど、環境に合わせた修正を行ってください。

// お客様ご使用の環境に関するお問い合わせにはお答えできません。

// echo "Content-type: text/plain\n\n";

 

 

 

//

// 使用する機能のWSDLを取得します。

$client = new SoapClient(

'WSDLURIを指定してください',

array('trace' => TRUE)

  );

 

//

// 引数を準備します

$params = array(

  'contentProviderID' => '契約時にご提供するコンテンツプロバイダIDを設定してください',

  'contentProviderPassword' => 'コンテンツプロバイダパスワードを設定してください',

  'contentID' => 'コンテンツIDを指定してください',

  'expireDays' => '3' // 初回再生許可時からいつまで再生を許可するかを日単位で指定してください

);

 

//

// 当サンプルでは、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";

}

//

// 以下のプログラムコードは、通信内容を、送信時のものと受信時のものとに分けて

// すべて表示します。

// 動作確認やログ取得用などに、改造して適宜ご利用ください。

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. その他の言語
その他の言語につきましては、当社での調査が行われ次第、本ドキュメントへの記載を追加したいと考えております。もしお客様が本ドキュメントへ記載されている例以外の環境・言語への実装に成功した場合、当社へのフィードバックを歓迎いたします。
 Copyright (C) 2006 RTV. All Rights Reserved.