料金や利用量の取得機能をアプリケーションに組み込む (料金・利用量集計 API)

はじめに

この文書では RICOH Live Streaming REST API: 料金・利用量集計 API v1 の使い方を紹介しています。

料金・利用量集計 API の概要とユースケース

RICOH Live Streaming REST API: 料金・利用量集計 API v1 は、あるクライアントの RICOH Live Streaming の利用料金と利用量の集計結果を集計対象期間を指定して取得する REST API を提供します。この API を利用することで以下のことができるようになります。

  • アプリケーション全体の RICOH Live Streaming の利用料金や利用量を知る
  • アプリケーションの利用者ごとに分類された RICOH Live Streaming の利用料金や利用量を知る

アプリケーション全体の RICOH Live Streaming の利用料金や利用量を知る

API を利用することで、請求書の発行を待たなくても、いつでも指定した集計期間中の利用料金と利用量を取得することができます。

これを利用して、即時性の高い情報を把握してコスト管理の最適化を行ったり、BI ツールなどを組み合わせてビジュアライゼーションを行い、月次だけでなく週次や日次での変化をチェックしたりするなど、ビジネスの最適化につなげることができます。

※ 集計期間の指定可能な範囲には制約があります。詳細は 料金・利用量集計 API の制約 を参照してくだい。

アプリケーションの利用者ごとに分類された RICOH Live Streaming 利用料金と利用量を知る

アプリケーションの利用者に対して RICOH Live Streaming の利用量に応じた料金を請求したいなど、利用者ごとの RICOH Live Streaming の利用量を把握したい場面では、利用者ごとにつけた「課金分類ラベル」によって分類された利用料金と利用量を取得する事ができます。

課金分類ラベルとは「利用量の内訳を取得するには」で説明されている classification_label のことで、アプリケーションが Access Token に利用者を特定可能な文字列を付与することによって、「利用者ごと」など、管理/把握したい単位で利用料金や利用量を収集することを可能にします。

料金・利用量集計 API の提供機能

上記を実現するため、以下の 3 種類の取得方法の API が提供されます。

前提: RICOH Live Streaming の利用料金について

API の利用方法の解説の前に、前提となる RICOH Live Streaming の利用料金について簡単におさらいします。

料金計算

RICOH Live Streaming の利用料金は、「RICOH Live Streaming Service 利用料金」に記載されている通り、以下の 3 つの料金を合計した従量課金です。

  • 接続基本料金
    • 接続形態(P2P/TURN, SFU)によらず、接続ごとの延べ接続時間(分単位)に対する課金額
  • 通信量料金
    • TURN サーバー利用時や、SFU サーバー利用時にのみ課金される、実際のデータ通信量に対する課金額
  • Room 帯域幅予約料金
    • SFU サーバー利用時にのみ課金される、Room の最大帯域幅設定値と Room 利用時間(分単位)に対する課金額

具体的な金額については、「RICOH Live Streaming Service 料金表」をご参照ください。

これら 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 で発生した料金が含まれます。

料金・利用量集計 API の利用方法

上述した 3 種類の取得方法の API について、実際に料金・利用量集計 API を利用する例を以下に説明します。

以下の条件で料金と利用量を取得します。

  • 2022 年 4 月 25 日締めの請求分 (2022 年 3 月 26 日から 2022 年 4 月 25 日利用分)
  • 本番環境 (prod)

curl を利用したシェルスクリプトを例にします。実際にはアプリケーションの開発で利用している言語に変換してお使いください。

認証には発行された ClientID と ClientSecret を利用した BASIC 認証を必要とします。環境変数にCLIENT_IDCLIENT_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" | jq

URL のパスで /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_labellabel1 に設定されたデータのみを取得することができました。

課金分類ラベルごとに分類された料金・利用量集計結果の取得

コマンドの実行例は以下です。

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" | jq

料金・利用量集計 API の制約

RICOH Live Streaming REST API: 料金・利用量集計 API v1 は、集計期間について以下の制約があります。

  • 集計可能なのは過去 1 年以内
  • 集計可能な期間の範囲は最大 1 ヶ月間

上記の制約を満たさないリクエストに対してはエラーレスポンスが返却されます。

また、本 API から取得されるデータの保証については以下です。

  • 終了後 24 時間以上経過した RoomInstance について確定した値が算入されていることを保証し、それ未満のものに関しては推定値とする

例えば、2022-04-10T09:00:00Z に終了した RoomInstance を含む料金・利用量は、2022-04-11T09:00:00Z 以降に確定した値が算入されていることが保証されます。

まとめ

本文書では「料金・利用量集計 API」の概要とユースケース、利用方法について紹介しました。
この機能を活用して、RICOH Live Streaming を利用したお客様のビジネスの最適化に繋がれば幸いです。

ドキュメント

メッセージング機能

セキュリティホワイトペーパー