openapi: 3.0.0
info:
  title: User APIs requirements
  version: '1.0'
  description: >

    本項で定義されるAPIは、CWS APIからの特定リソース取得目的で、ご利用者様に用意いただくAPI仕様を定義します。


    APIを用意いただくことで、CWS APIから特定リソースを取得することが可能となります。


    ## ファイルアップロード機能とは？


    CWS APIでは、THINKLETデバイスにインストールしたご利用者様アプリから、ご指定のストレージ（Amazon
    S3）に対してファイルをアップロードする機能を提供しています。


    詳細について、[**ファイルアップロード用署名付きURL取得**](#tag/FileUpload) を参照ください。
servers:
  - url: https://<yourserver.yourdomain>
    description: ご利用者様のWebサーバー
security:
  - X-TLPF-NOTIFICATION-KEY: []
paths:
  /"録画データ（Sora）用署名付きURL取得URL（マルチパート対応）":
    post:
      summary: 録画データ（Sora）用署名付きURL発行（マルチパート対応）
      operationId: post-sora-rec-get-multi-presigned-url
      description: >-
        Soraの録画データをAmazon S3にアップロードするための、署名付きURL（マルチパート対応）を発行します。


        [通知・アクセス設定](/apis/v1/cws_api#tag/Config/operation/patch-v1-applications)にて「録画データ（Sora）用署名付きURL取得URL（マルチパート対応）`soraRecGetMultiPresignedUrl`
        」に登録したURLに対して、CWS APIから呼び出します。


        マルチパートの署名付きURLを発行する対象は、webm（Request bodyの`webmFile`で指定した）ファイルのみです。

        指定した分割数（Request bodyの`splitted`で指定した数）のURLを発行してください。

        指定した分割数と発行したURLの数が一致しない場合、録画データのアップロードは失敗します。


        発行したマルチパートの署名付きURLは、発行した順にレスポンスのリストに格納してください。異なる順序でリストに格納された場合、アップロードされた録画データは正しく再生されません。


        json（Request
        bodyの`metaFile`、`jsonFile`で指定した)ファイルに対しては、マルチパートではない署名付きURLを発行してください。


        なお、マルチパートの署名付きURLは、ファイルアップロードの後に完了処理が必要となります。

        本APIで発行した署名付きURLの完了処理は、利用者様にてご用意ください。


        完了処理の実行は、[通知・アクセス設定](/apis/v1/cws_api#tag/Config/operation/patch-v1-applications)の「Sora録画データ通知先URL`soraFileSendEvent`」に指定した[録画データ通知](/apis/v1/cws_notification#tag/Sora-Recorded-Event/operation/post-sora-save-event)を受信したタイミングで実施してください。
      parameters:
        - schema:
            type: string
          in: header
          name: X-TLPF-NOTIFICATION-KEY
          description: 署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)
        - schema:
            type: string
          in: header
          name: applicationId
          description: アプリケーションID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiPresignedURLRequest'
            examples:
              コネクションが1つの場合:
                value:
                  channel:
                    channelId: 01954c30-4b29-4a03-b7e8-335f1fd145ea
                    metaFile: HE3010HSF92T5E3JKVDW9MN0QR.json
                    connections:
                      - connectionId: 1D0F0P98XX0W1FSBY4ZSV0E428
                        jsonFile: RSSWN3F0YS2P794XGFBW22MXG4.json
                        webmFile:
                          file: RSSWN3F0YS2P794XGFBW22MXG4.webm
                          splitted: 2
              コネクションが複数の場合:
                value:
                  channel:
                    channelId: 01954c30-4b29-4a03-b7e8-335f1fd145ea
                    metaFile: HE3010HSF92T5E3JKVDW9MN0QR.json
                    connections:
                      - connectionId: 1D0F0P98XX0W1FSBY4ZSV0E428
                        jsonFile: RSSWN3F0YS2P794XGFBW22MXG4.json
                        webmFile:
                          file: RSSWN3F0YS2P794XGFBW22MXG4.webm
                          splitted: 2
                      - connectionId: ZGJCGBTWBH23Z6PRKNR6YGQ138
                        jsonFile: BZBW9RTSC95V94Z0XWFS0FGJS0.json
                        webmFile:
                          file: BZBW9RTSC95V94Z0XWFS0FGJS0.webm
                          splitted: 3
                      - connectionId: xxxxxxxxxxxxxxxxxxxxxx
                        jsonFile: xxxxxxxxxxxxxxxxxxxxxxxxx.json
                        webmFile:
                          file: xxxxxxxxxxxxxxxxxxxxxxxxx.webm
                          splitted: 2
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiPresignedURLResponse'
              examples:
                コネクションが1つの場合:
                  value:
                    HE3010HSF92T5E3JKVDW9MN0QR.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    RSSWN3F0YS2P794XGFBW22MXG4.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    RSSWN3F0YS2P794XGFBW22MXG4.webm:
                      uploadId: >-
                        OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE
                      parts:
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                コネクションが複数の場合:
                  value:
                    HE3010HSF92T5E3JKVDW9MN0QR.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    RSSWN3F0YS2P794XGFBW22MXG4.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    RSSWN3F0YS2P794XGFBW22MXG4.webm:
                      uploadId: >-
                        OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE
                      parts:
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    BZBW9RTSC95V94Z0XWFS0FGJS0.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    BZBW9RTSC95V94Z0XWFS0FGJS0.webm:
                      uploadId: >-
                        tZ20sgEAhQeApnMVW_yqg9j4swb3wKbE1DUo_FR64uQEy2DXrshomngSwPgPxj5wGjINj3AGU1ITHQ-hi4Z2FEXAMPLE
                      parts:
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    xxxxxxxxxxxxxxxxxxxxxx.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    xxxxxxxxxxxxxxxxxxxxxx.webm:
                      uploadId: >-
                        ud3N7J8YjCEW21dIC_OIe0WAjz4jvgjTVbAU_4Wnzy3TgGST5lSWpCQu4nm2gZqqc8cHx2WelIXqIS-essuHIEXAMPLE
                      parts:
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
        '400':
          description: Bad Request - 入力値誤りなど
        '500':
          description: Internal Server Error - 内部エラー（DB接続時エラーなど）
      tags:
        - WebRTC(Sora)
  /"ファイルアップロード用署名付きURL取得URL":
    post:
      summary: ファイルアップロード用署名付きURL取得
      operationId: post-file-upload-get-presigned-url
      description: >-
        ご利用者様が作成したアプリでTHINKLETデバイス上に保存したファイルを、ご利用者様環境のストレージ（Amazon
        S3）へアップロードするために、**ご利用者様自身で用意するための環境準備およびAPI仕様**を記載します。


        ### ファイルアップロードシーケンス


        ![illustration](/img/apis/file_upload_illustration.png)


        #### ポイント1


        本ファイルアップロード機能を利用する事前準備として、[通知・アクセス設定](/apis/v1/cws_api#tag/Config/operation/patch-v1-applications)にて下記設定をしてください。


        - `fileUploadGetUrl` (ファイルアップロード用署名付きURL取得URL) **本項APIのURL**

        - `fileUploadEvent`
        ([ファイルアップロードイベント通知先URL](/apis/v1/cws_notification#tag/File-Upload-Event/operation/post-file-upload-event))


        上記の設定、取得に関しては、[CWS APIリファレンス](/apis/v1/cws_api)の下記を参照ください。


        -
        [通知・アクセス設定](/apis/v1/cws_api#tag/Config/operation/patch-v1-applications)

        -
        [通知・アクセス設定内容取得](/apis/v1/cws_api#tag/Config/operation/get-v1-applications)


        #### ポイント２


        デバイス内に保存したファイルのアップロードは、THINLKET内のご利用者様アプリから、デバイス内の当社提供インタフェースに対してリクエストすると開始されます。


        上記インタフェース仕様については、本ファイルアップロード機能の利用を希望いただいたご利用者様に個別に提供しております。


        ご希望の方は当社にお問い合わせください。


        #### ポイント３


        CWS APIは、下記に設定されたURLを利用してAPIをコールします。


        - `fileUploadGetUrl` (ファイルアップロード用署名付きURL取得URL) **本項APIのURL**


        **APIは本項の仕様に準拠している必要があります。**


        #### ポイント４


        CWS APIは、下記に設定されたURLを利用してファイルアップロード実行の成功/失敗のイベントを通知します。


        - `fileUploadEvent`
        ([ファイルアップロードイベント通知先URL](/apis/v1/cws_notification#tag/File-Upload-Event/operation/post-file-upload-event))


        通知イベントにより、必要な処理を行なってください。


        ### 特記事項


        - `fileUploadGetUrl`で取得できる署名付きURLは、Single Partにのみ対応します。

        - AWS S3のSingle Part Uploadの使用に準拠し、CWS APIとしてはファイル種別等の制限はありません。


        ### 制限事項


        -
        `fileUploadGetUrl`または[`fileUploadEvent`](/apis/v1/cws_notification#tag/File-Upload-Event/operation/post-file-upload-event))が設定されていない場合は、ファイルアップロードは利用できません。

        - アップロード対象のファイルサイズは、**1Byte以上、20MByte以下**となります。
          - ファイルサイズが本範囲内に収まらない場合、ファイルアップロードは利用できません。
      parameters:
        - schema:
            type: string
          in: header
          name: X-TLPF-NOTIFICATION-KEY
          description: 署名検証のハッシュ値(payloadとauthenticationKeyのHMAC-SHA256)
        - schema:
            type: string
          in: header
          name: applicationId
          description: アプリケーションID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUploadPresignedURLRequest'
            examples:
              ファイルアップロード用署名付きURL要求:
                value:
                  deviceId: 1D0F0P98XX0W1FSBY4ZSV0E428
                  file: <application_id>/<device_id>/upload_files/hogehoge.log
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadPresignedURLResponse'
              examples:
                ファイルアップロード用署名付きURL:
                  value:
                    url: <ファイルアップロード用署名付きURL>
        '400':
          description: Bad Request - 入力値誤りなど
        '500':
          description: Internal Server Error - 内部エラー（DB接続時エラーなど）
      tags:
        - FileUpload
components:
  securitySchemes:
    X-TLPF-NOTIFICATION-KEY:
      type: http
      scheme: header
  schemas:
    MultiPresignedURLRequest:
      title: MultiPresignedURLRequest
      description: マルチパート対応の署名付きURL取得（リクエスト）モデル
      type: object
      example:
        channel:
          channelId: 01954c30-4b29-4a03-b7e8-335f1fd145ea
          metaFile: HE3010HSF92T5E3JKVDW9MN0QR.json
          connections:
            - connectionId: 1D0F0P98XX0W1FSBY4ZSV0E428
              jsonFile: RSSWN3F0YS2P794XGFBW22MXG4.json
              webmFile:
                file: RSSWN3F0YS2P794XGFBW22MXG4.webm
                splitted: 2
            - connectionId: ZGJCGBTWBH23Z6PRKNR6YGQ138
              jsonFile: BZBW9RTSC95V94Z0XWFS0FGJS0.json
              webmFile:
                file: BZBW9RTSC95V94Z0XWFS0FGJS0.webm
                splitted: 1
      properties:
        channel:
          type: object
          description: チャネル
          items:
            type: object
            properties:
              channelId:
                type: string
                description: チャネルID
              metaFile:
                type: string
                description: 全体メタファイル
              connections:
                type: array
                description: コネクション
                items:
                  type: object
                  description: （※コネクション数分存在）
                  properties:
                    connectionId:
                      type: string
                      description: コネクションID
                    jsonFile:
                      type: string
                      description: 個別の映像音声ファイルのメタデータ
                    webmFile:
                      type: object
                      description: 動画音声ファイル
                      properties:
                        file:
                          type: string
                          description: ファイル名
                        splitted:
                          type: integer
                          description: 分割数
                  required:
                    - connectionId
                    - jsonFile
                    - webmFile
          required:
            - channelId
            - metaFile
    MultiPresignedURLResponse:
      title: MultiPresignedURLResponse
      type: object
      description: マルチパート対応署名付きURL取得（レスポンス）モデル
      example:
        HE3010HSF92T5E3JKVDW9MN0QR.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
        RSSWN3F0YS2P794XGFBW22MXG4.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
        RSSWN3F0YS2P794XGFBW22MXG4.webm:
          uploadId: >-
            OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE
          parts:
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
        BZBW9RTSC95V94Z0XWFS0FGJS0.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
        BZBW9RTSC95V94Z0XWFS0FGJS0.webm:
          uploadId: >-
            tZ20sgEAhQeApnMVW_yqg9j4swb3wKbE1DUo_FR64uQEy2DXrshomngSwPgPxj5wGjINj3AGU1ITHQ-hi4Z2FEXAMPLE
          parts:
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
        xxxxxxxxxxxxxxxxxxxxxx.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
        xxxxxxxxxxxxxxxxxxxxxx.webm:
          uploadId: >-
            ud3N7J8YjCEW21dIC_OIe0WAjz4jvgjTVbAU_4Wnzy3TgGST5lSWpCQu4nm2gZqqc8cHx2WelIXqIS-essuHIEXAMPLE
          parts:
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
      additionalProperties:
        oneOf:
          - type: string
          - type: object
        description: |-
          発行した署名付きURL。
          jsonファイルの場合、string型となり、発行した署名付きURLを格納する。
          webmファイルの場合、object型となり、以下を格納する。
          - 署名付きURLのuploadId
          - Request bodyの`splitted`の数、マルチパートの署名付きURL
    FileUploadPresignedURLRequest:
      title: FileUploadPresignedURLRequest
      type: object
      description: ファイルアップロード用署名付きURL取得（リクエスト）モデル
      example:
        deviceId: 1D0F0P98XX0W1FSBY4ZSV0E428
        file: <ご利用者様アプリケーションID>/<ご利用者様デバイスのデバイスID>/upload_files/<任意のパス/ファイル名>
      properties:
        deviceId:
          type: string
          description: デバイスID
        file:
          type: string
          description: アップロード対象ファイルの相対パス
      required:
        - deviceId
        - file
    FileUploadPresignedURLResponse:
      title: FileUploadPresignedURLResponse
      type: object
      description: ファイルアップロード用署名付きURL取得（レスポンス）モデル
      example:
        url: https://xxxxxxxxxxxxxxxxxxxxxxxxx
      properties:
        url:
          type: string
          description: 発行したファイルアップロード用署名付きURL
      required:
        - url
tags:
  - name: WebRTC(Sora)
    description: Sora録画データ
  - name: FileUpload
    description: ファイルアップロード