「Surfly REST API Documentation」の利用マニュアル

「Surfly REST API Documentation」の利用マニュアル

個々のスペースのカスタマイズなどを可能にし、スペースの使い方の可能性がより広がる「Surfly REST API Documentation」の基本的なご利用方法についてご紹介します。

「Surfly REST API Documentation」へのアクセス方法

Surflyのダッシュボードで、左側から「スペース」を選択して、スペースの管理画面を開きます。
下部に「Spaces REST APIs」が表示されるので、そちらをクリックしてください。


「Surfly REST API Documentation」でできること

・オペレーターが作成したスペースの情報（スペースIDや、永続スペースかどうか）を確認
・既存スペースのオプション設定値の確認・変更、削除
・その他、スペースの作成・削除など　※ダッシュボード上でも可能です

「Surfly REST API Documentation」の注意事項

オペレーターのアカウントをお持ちのユーザーであれば誰でもドキュメントの参照が可能ですが、管理者のみがREST APIキーにアクセスできます。
そのため、このドキュメントを使ってのREST APIの実行は、管理者権限を持つユーザーのみが可能となります。

「Surfly REST API Documentation」のご利用方法

ドキュメント内でREST APIの実行を行う場合

このドキュメント内で自身のREST APIキーを提供すると、ドキュメント内の各アクションで「Try It Out」ボタンから実行可能になります。
この機能を利用するには、右上の「Authorize」ボタンからREST APIキーを入力してください。


REST APIを実行せずに、curlコマンドの実行文のみを知りたい場合

本マニュアルでは、REST APIキーを入力してドキュメント内で実行することを想定しています。
実行文だけ確認したい場合は、REST APIキーは入力せずに各項目の「Execute」ボタンを押して、結果に出てくるcurl実行文をコピーしてお使いください。

※上の画像は、REST APIキーを入力せずに、「[GET] /v3/spaces/」の「Execute」ボタンを押した結果の例です。
　curl文のコードの右下にコピーボタンがありますので、そこからコピーして自由にご利用ください。
　ただし、リクエストURLは、「https://app.surfly.jp/v3/spaces/?api_key=******」という形式でREST APIキーを記載したものに書き換える必要があります。
※この方法では、サーバーレスポンスとして「Error: response status is 403」のエラーメッセージが表示されるため、ドキュメント内で実行されることはありません。

「Surfly REST API Documentation」での実行例

作成済みスペースの一覧情報を取得

作成済みスペースの一覧情報を取得する方法をご紹介します。
  1. 「[GET] /v3/spaces/」の項目をクリックして詳細を開き、「Try it out」をクリックします。

  2. いくつか入力欄が表示されますが、何も入力せずに「Execute」をクリックします。
    ※各パラメーターのご利用方法については以下をご参照ください。
    Name

    ordering
    どのフィールドを基にした順番で、結果を表示するかをstring型で入力します。
    ※例：スラッグを基にソートしたい場合には"slug"と入力します。
    page
    		結果に表示したいページ番号をinteger型で入力します。
    ※"page_size"と併せてご使用ください。
    page_size
    		各ページにいくつの結果(※スペースの数のこと)を表示するかinteger型で入力します。
    ※例：スペースの数が100ある場合、「2」を入力すると50ページに結果が分割されます。デフォルトでは1ページ目の結果が表示されますので、"page"で表示したいページ番号を指定してください。
    search
    ここにstring型で入力した値を含む結果のみを結果に表示します。

  3. 実行後、結果が表示されます。表示結果は右下のボタンからコピー、またはjsonファイルでのダウンロードが可能です。

新しいスペースを作成する

ダッシュボードでもスペースの作成は可能ですが、REST APIからの作成には以下の利点があります。
  1. 他のオペレーターがオーナーのスペースが作成可能になる
  2. (ドキュメントから実行した場合のみ)ランダムな文字列のスラッグが使用可能になる
※「type」の設定項目では将来的にセッションタイプが指定できるようになる予定ですが、現在はサポート対象外です。
  1. 「[POST] /v3/spaces/」の項目をクリックして詳細を開き、「Try it out」をクリックします。
  2. "Request Body"の中身が変更できるので、必要に応じて編集します。以下は、開始URLとホスト資格のあるユーザーは何も指定せずに一時スペースを作る場合の例です。

  3. 「Execute」をクリックして、エラーが出なければスペースの作成は成功です。エラーが出た場合にはメッセージに従ってRequest Bodyの修正を行ってください。作成されたスペースは、ダッシュボードからも確認が可能です。

作成済みスペースの情報を変更する

作成済みスペースの情報を変更する方法をご紹介します。「作成済みスペースの一覧情報を取得」の項目を参考に、変更したいスペースのIDを事前にご確認ください。
  1. 「[PUT] /v3/spaces/{id}/」の項目をクリックして詳細を開き、「Try it out」をクリックします。
  2. 「id」の入力欄に、スペースのIDを入力します。
  3. Request Bodyの中身を適宜変更します。スペースのオーナーとなるオペレーターのIDを変更できる他、一時スペースだったものを永続スペースに変更したりすることが可能です。　※変更のない項目もすべて定義し直してください。
  4. 「Execute」をクリックして、エラーが出なければスペースの変更は成功です。反映された変更はダッシュボードからも確認が可能です。

作成済みスペースで一部の設定オプションを固定する

作成したスペースには、ダッシュボードオプションの値がデフォルトで設定されます。しかし、各スペースで異なる設定オプションの値を固定させることができます。
一部のオプションのみを固定することができ、固定してないオプション設定に関してはダッシュボードでの変更がそのまま反映されます。
  1. 「[PATCH] /v3/spaces/{space_id}/options/」の項目をクリックして詳細を開き、「Try it out」をクリックします。
  2. 「id」の入力欄に、スペースのIDを入力します。
  3. Request Bodyの中身を適宜変更します。初期値ではすべてのオプションが、trueもしくは"string"となっています。そのため、固定したいオプションのみについて値を指定することを推奨します。
    例：セッションの開始と同時にビデオチャットを自動で開始し、全画面モードからビデオチャットを行いたい場合
  4. 「Execute」をクリックして、エラーが出なければオプションの固定は完了です。「[GET] /v3/spaces/{space_id}/options/」を使って固定されたオプションは確認可能です。
    ※現在古いオプション名もサポートしているため、Response bodyには旧オプション名も併せて表示されます。新旧オプション名の対応についてはこちらをご参照ください。

スペースで固定した設定オプションを解除する

スペースで固定した設定オプションを解除する方法についてご紹介します。
  1. 「[DELETE] /v3/spaces/{space_id}/options/」の項目をクリックして詳細を開き、「Try it out」をクリックします。
  2. 「space_id」に該当のスペースのIDを入力します。
  3. 「Execute」をクリックします。設定オプションの固定が解除されたかどうかは、「[GET] /v3/spaces/{space_id}/options/」でご確認ください。





    • Related Articles

    • Surflyで取得可能なログ/アーカイブについて

      Surflyで取得可能なログやアーカイブには以下のものがあります。 名称 保存場所 保存期間 ファイル形式 記録On/Off制御 ①セッション履歴ログ Surflyデータベース 無制限 提供時はCSV 制御不可（常に記録） ②セッション監査ログ S3ストレージ ストレージ側の仕様による JSON 制御可 ③スクリーンショットアーカイブ S3ストレージ ストレージ側の仕様による PNG 制御可 ④セッション録画アーカイブ S3/GONGストレージ ストレージ側の仕様による MP4 制御可 ...

    • Surflyの動作要件を教えてください

      Surflyは、ブラウザが存在する環境であればデスクトップ端末でもモバイル端末でもご利用が可能です。 ブラウザはChrome、Edge、Firefox、Safariの最新バージョンで使用が可能です。（※デスクトップ端末をご利用の場合） その他の要件、通信環境などの詳細については、「製品概要」ページの「2 Surflyの動作要件」をご参照ください。

    • Surflyセッションとは何ですか。

      Surflyでは「セッション」というものを開始することで、コブラウズやビデオチャット、ドキュメント編集といった様々な機能を利用したリモートコラボレーションを開始することができます。 コブラウジングは、Surflyセッションの中で利用可能な主要機能です。 Surflyセッションは、どんなURLからも開始可能です。セッションはブラウザの一つのタブの中ですべて行われます。他のWebページに移動したり、ドキュメントを共有するなどの作業もすべて、この「セッション」の中で完結することができます。 ...

    • Surflyは他のコブラウズ製品と何が違いますか。

      一般的なコブラウズ製品はWebサイトやデジタルアプリケーションに、専用のコードを埋め込むか、何かアプリケーションをダウンロードする必要があります。 Surflyでは、このような事前準備なしにすぐコブラウジングを利用することができます。 ※アウトバウンドセッションもしくはスペースをご利用の場合に限ります。インバウンドセッションを使用する場合には、コードの埋め込みが必要になります。 ※セッションの形式に関わらず、アプリケーションのダウンロードなどは必要ありません。 ...

    • Surflyのコブラウジングの仕組みを教えてください

      ■一般的なブラウジング 標準ブラウザでWebページ閲覧を行う場合、使用しているブラウザがWebサイトにリクエストを送り、返ってきたレスポンスを基にページを表示します。 例）PC1がWebサイト”www.oceanbridge.jp”を標準ブラウザで閲覧する場合 　このとき、接続元はPC1、接続先は目的のWebサイト"www.oceanbridge.jp"となります。 ■Surflyでのコブラウジング ...