この文書では RICOH Live Streaming REST API: 料金・利用量集計 API v1 の使い方を紹介しています。
RICOH Live Streaming REST API: 料金・利用量集計 API v1 は、あるクライアントの RICOH Live Streaming の利用料金と利用量の集計結果を集計対象期間を指定して取得する REST API を提供します。この API を利用することで以下のことができるようになります。
API を利用することで、請求書の発行を待たなくても、いつでも指定した集計期間中の利用料金と利用量を取得することができます。
これを利用して、即時性の高い情報を把握してコスト管理の最適化を行ったり、BI ツールなどを組み合わせてビジュアライゼーションを行い、月次だけでなく週次や日次での変化をチェックしたりするなど、ビジネスの最適化につなげることができます。
※ 集計期間の指定可能な範囲には制約があります。詳細は 料金・利用量集計 API の制約 を参照してください。
アプリケーションの利用者に対して RICOH Live Streaming の利用量に応じた料金を請求したいなど、利用者ごとの RICOH Live Streaming の利用量を把握したい場面では、利用者ごとにつけた「課金分類ラベル」によって分類された利用料金と利用量を取得する事ができます。
課金分類ラベルとは「利用量の内訳を取得するには」で説明されている classification_label のことで、アプリケーションが Access Token に利用者を特定可能な文字列を付与することによって、「利用者ごと」など、管理/把握したい単位で利用料金や利用量を収集することを可能にします。
上記を実現するため、以下の 3 種類の取得方法の API が提供されます。
API の利用方法の解説の前に、前提となる RICOH Live Streaming の利用料金について簡単におさらいします。
RICOH Live Streaming の利用料金は、「利用料金の概要」に記載されている通り、以下の 3 つの料金を合計した従量課金です。
具体的な金額については、「利用料金の概要」をご参照ください。
これら 3 項目の内、アプリケーションを開発する上でコスト最適化のために重要なのが Room 帯域幅予約料金です。
Room 帯域幅予約の設定値は Room に接続する拠点が利用可能な帯域幅(Mbps)の合計値であり、この値と利用時間によって料金が決まります。
たとえ実際の通信の合計帯域が Room 帯域幅予約の設定値に満たない場合でも、設定値に応じた請求が発生するため無駄のない Room 帯域幅予約の設定を行うことがコスト最適化において重要です。
RICOH Live Streaming 料金計算ツールを利用し、アプリケーションに必要な拠点の種類や数、映像品質を設定することで最適な Room 帯域幅予約設定値を算出できますので、ご利用ください。
締日から翌月の締日の間に作成された RoomInstance に関する利用料金がその月の利用料金として請求されます。
RoomInstance が締日を跨いで継続した場合、その RoomInstance が作成された月、つまり締日前の月の請求にその RoomInstance の利用料金が含まれます。
例えば、毎月 UTC で 25 日から翌月の 25 日までのに発生した料金で請求が行われる場合、2022-04-25(UTC)に開始した RoomInstance が日を跨いで 2022-04-26(UTC)まで続くと、3/26 ～ 4/25 の利用分の請求にその RoomInstance で発生した料金が含まれます。
上述した 3 種類の取得方法の API について、実際に料金・利用量集計 API を利用する例を以下に説明します。
以下の条件で料金と利用量を取得します。
curl を利用したシェルスクリプトを例にします。実際にはアプリケーションの開発で利用している言語に変換してお使いください。
認証には発行された ClientID と ClientSecret を利用した BASIC 認証を必要とします。環境変数にCLIENT_ID と CLIENT_SECRET が設定されているものとします。
export CLIENT_ID=ClientID
export CLIENT_SECRET=ClientSecretコマンドの実行例は以下です。
curl -u $CLIENT_ID:$CLIENT_SECRET -X GET "https://api.livestreaming.mw.smart-integration.ricoh.com/v1/clients/$CLIENT_ID/cost_and_usage/total?since=2022-03-26T00:00:00Z&until=2022-04-26T00:00:00Z&env=prod" | jq上記のコマンドでは、クエリパラメータで以下の項目を指定しています。
since=2022-03-26T00:00:00Z: 集計期間の開始時刻until=2022-04-26T00:00:00Z: 集計期間の終了時刻 (この瞬間を含まない範囲が取得される)env=prod: 対象の環境 (prod / dev / 指定しない場合は両方の合計)レスポンスの例は以下です。
{
"results": [
{
"approximate_total_cost": 986954.5454,
"items": [
{
"item_name": "connection_time",
"approximate_cost": 742.98,
"usage": 74298
},
{
"item_name": "traffic_volume",
"approximate_cost": 32250,
"usage": 1075
},
{
"item_name": "bitrate_reservation",
"sub_items": [
{
"item_name": "31",
"approximate_cost": 5370.9105,
"usage": 995
},
{
"item_name": "43",
"approximate_cost": 121040.304,
"usage": 12320
},
{
"item_name": "187",
"approximate_cost": 827550.3509,
"usage": 14689
}
]
}
]
}
]
}集計期間内にクライアントが利用した利用量と、その料金の概算値を取得できました。
approximate_total_cost が集計期間内の利用料金の合計の概算値で、items の各項目の approximate_cost がその項目の利用料金の概算値です。それぞれ単位は日本円です。
各項目の仕様の詳細に関しては、API 仕様書 を参照してください。
label1 という課金分類ラベルについて料金・利用量集計結果を取得する場合のコマンドの実行例は以下です。
※ 課金分類ラベルに、利用者名などの個人情報を類推できる文字列は設定しないでください
curl -u $CLIENT_ID:$CLIENT_SECRET -X GET "https://api.livestreaming.mw.smart-integration.ricoh.com/v1/clients/$CLIENT_ID/cost_and_usage/classification_labels/label1?since=2022-03-26T00:00:00Z&until=2022-04-26T00:00:00Z&env=prod" | jqURL のパスで /classification_labels/label1 を指定しています。
クエリパラメータについては上記と同様です。
コマンドの実行例は以下です。
{
"results": [
{
"classification_label": "label1",
"approximate_total_cost": 17473.8913,
"items": [
{
"item_name": "connection_time",
"approximate_cost": 18.85,
"usage": 1885
},
{
"item_name": "traffic_volume",
"approximate_cost": 1057.617,
"usage": 35.2539
},
{
"item_name": "bitrate_reservation",
"sub_items": [
{
"item_name": "43",
"approximate_cost": 16397.4243,
"usage": 1669
}
]
}
]
}
]
}classification_label が label1 に設定されたデータのみを取得することができました。
コマンドの実行例は以下です。
curl -u $CLIENT_ID:$CLIENT_SECRET -X GET "https://api.livestreaming.mw.smart-integration.ricoh.com/v1/clients/$CLIENT_ID/cost_and_usage/classification_labels?since=2022-03-26T00:00:00Z&until=2022-04-26T00:00:00Z&env=prod" | jqクエリパラメータについては上記と同様です。
{
"results": [
{
"classification_label": "label1",
"approximate_total_cost": 17473.8913,
"items": [
{
"item_name": "connection_time",
"approximate_cost": 18.85,
"usage": 1885
},
{
"item_name": "traffic_volume",
"approximate_cost": 1057.617,
"usage": 35.2539
},
{
"item_name": "bitrate_reservation",
"sub_items": [
{
"item_name": "43",
"approximate_cost": 16397.4243,
"usage": 1669
}
]
}
]
},
{
"classification_label": "label2",
"approximate_total_cost": 999.8101,
"items": [
{
"item_name": "connection_time",
"approximate_cost": 1.12,
"usage": 112
},
{
"item_name": "traffic_volume",
"approximate_cost": 84.993,
"usage": 2.8331
},
{
"item_name": "bitrate_reservation",
"sub_items": [
{
"item_name": "43",
"approximate_cost": 913.6971,
"usage": 93
}
]
}
]
},
{
"classification_label": "label3",
"approximate_total_cost": 15449.924,
"items": [
{
"item_name": "connection_time",
"approximate_cost": 4.88,
"usage": 488
},
{
"item_name": "traffic_volume",
"approximate_cost": 233.757,
"usage": 7.7919
},
{
"item_name": "bitrate_reservation",
"sub_items": [
{
"item_name": "187",
"approximate_cost": 15211.287,
"usage": 270
}
]
}
]
}
]
}classification_label ごとに分類されたデータを取得することができました。
課金分類ラベルごとに分類された料金・利用量集計結果の取得 の API では、クエリパラメータに starts_with を指定することが可能です。
これは、課金分類ラベルのプレフィックスが starts_with で指定した文字列で始まるものだけを抽出します。
これを利用することで、課金分類ラベルに 利用者を特定できる文字列_Room名 というような構造化した文字列を付与し、starts_with=利用者を特定できる文字列 でクエリした場合に、指定した利用者が利用した Room ごとの料金・利用量を収集することができます。利用者を特定できる文字列には、UUID や利用者名から計算したハッシュ値、 DB のサロゲートキーなど、個人情報を類推できない文字列を利用してください。
課金分類ラベルには利用者だけではない情報を持たせて分類することができます。
コマンドの実行例は以下です。
curl -u $CLIENT_ID:$CLIENT_SECRET -X GET "https://api.livestreaming.mw.smart-integration.ricoh.com/v1/clients/$CLIENT_ID/cost_and_usage/classification_labels?since=2022-03-26T00:00:00Z&until=2022-04-26T00:00:00Z&env=prod&starts_with=label1" | jqRICOH Live Streaming REST API: 料金・利用量集計 API v1 は、集計期間について以下の制約があります。
上記の 制約を満たさないリクエストに対してはエラーレスポンスが返却されます。
また、本 API から取得されるデータの保証については以下です。
例えば、2022-04-10T09:00:00Z に終了した RoomInstance を含む料金・利用量は、2022-04-11T09:00:00Z 以降に確定した値が算入されていることが保証されます。
本文書では「料金・利用量集計 API」の概要とユースケース、利用方法について紹介しました。 この機能を活用して、RICOH Live Streaming を利用したお客様のビジネスの最適化に繋がれば幸いです。
この情報は役に立ちましたか？