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を発行する対象は、動画（Request bodyの`movieFile`で指定した）ファイルのみです。

        指定した分割数（Request bodyの`movieFile.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
                        movieFile: &ref_0
                          file: RSSWN3F0YS2P794XGFBW22MXG4.mp4
                          splitted: 2
                        webmFile: *ref_0
              コネクションが複数の場合:
                value:
                  channel:
                    channelId: 01954c30-4b29-4a03-b7e8-335f1fd145ea
                    metaFile: HE3010HSF92T5E3JKVDW9MN0QR.json
                    connections:
                      - connectionId: 1D0F0P98XX0W1FSBY4ZSV0E428
                        jsonFile: RSSWN3F0YS2P794XGFBW22MXG4.json
                        movieFile: &ref_1
                          file: RSSWN3F0YS2P794XGFBW22MXG4.mp4
                          splitted: 2
                        webmFile: *ref_1
                      - connectionId: ZGJCGBTWBH23Z6PRKNR6YGQ138
                        jsonFile: BZBW9RTSC95V94Z0XWFS0FGJS0.json
                        movieFile: &ref_2
                          file: BZBW9RTSC95V94Z0XWFS0FGJS0.mp4
                          splitted: 3
                        webmFile: *ref_2
                      - connectionId: xxxxxxxxxxxxxxxxxxxxxx
                        jsonFile: xxxxxxxxxxxxxxxxxxxxxxxxx.json
                        movieFile: &ref_3
                          file: xxxxxxxxxxxxxxxxxxxxxxxxx.mp4
                          splitted: 2
                        webmFile: *ref_3
        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.mp4:
                      uploadId: >-
                        OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE
                      parts:
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                コネクションが複数の場合:
                  value:
                    HE3010HSF92T5E3JKVDW9MN0QR.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    RSSWN3F0YS2P794XGFBW22MXG4.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    RSSWN3F0YS2P794XGFBW22MXG4.mp4:
                      uploadId: >-
                        OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE
                      parts:
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    BZBW9RTSC95V94Z0XWFS0FGJS0.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    BZBW9RTSC95V94Z0XWFS0FGJS0.mp4:
                      uploadId: >-
                        tZ20sgEAhQeApnMVW_yqg9j4swb3wKbE1DUo_FR64uQEy2DXrshomngSwPgPxj5wGjINj3AGU1ITHQ-hi4Z2FEXAMPLE
                      parts:
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                        - https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    xxxxxxxxxxxxxxxxxxxxxx.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
                    xxxxxxxxxxxxxxxxxxxxxx.mp4:
                      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は、Amazon
        S3の`PutObject`操作用に発行された署名付きURLです。CWS APIは、このURLを使用してSingle Part
        Uploadでファイルをアップロードします。アップロードに関する詳細な挙動は、AWSの仕様に準拠します。

        - CWS
        APIは、ご利用者様環境のストレージへファイルをアップロードする際、ファイルの種別に関わらずHTTPリクエストヘッダーの`Content-Type`を`application/octet-stream`として送信します。ファイルごとに異なる`Content-Type`を指定することはできません。

        -
        `application/octet-stream`以外の`Content-Type`をオブジェクトに設定したい場合は、アップロード完了後に、ご利用者様環境にてS3オブジェクトのメタデータ更新（`CopyObject`等）でご対応ください。

        - 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: '123456789101234'
                  applicationId: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
                  dir: logs/abcxxxxxxxxxxxxx/
                  file: 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
              movieFile: &ref_4
                file: RSSWN3F0YS2P794XGFBW22MXG4.mp4
                splitted: 2
              webmFile: *ref_4
            - connectionId: ZGJCGBTWBH23Z6PRKNR6YGQ138
              jsonFile: BZBW9RTSC95V94Z0XWFS0FGJS0.json
              movieFile: &ref_5
                file: BZBW9RTSC95V94Z0XWFS0FGJS0.mp4
                splitted: 1
              webmFile: *ref_5
      properties:
        channel:
          type: object
          description: チャネル
          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: 個別の映像音声ファイルのメタデータ
                  movieFile:
                    type: object
                    description: 動画音声ファイル
                    properties:
                      file:
                        type: string
                        description: ファイル名
                      splitted:
                        type: integer
                        description: 分割数
                  webmFile:
                    type: object
                    deprecated: true
                    description: 動画音声ファイル。互換性のために提供されており、movieFileと同内容。
                    properties:
                      file:
                        type: string
                        description: ファイル名
                      splitted:
                        type: integer
                        description: 分割数
                required:
                  - connectionId
                  - jsonFile
                  - movieFile
                  - webmFile
          required:
            - channelId
            - metaFile
    MultiPresignedURLResponse:
      title: MultiPresignedURLResponse
      type: object
      description: マルチパート対応署名付きURL取得（レスポンス）モデル
      example:
        HE3010HSF92T5E3JKVDW9MN0QR.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
        RSSWN3F0YS2P794XGFBW22MXG4.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
        RSSWN3F0YS2P794XGFBW22MXG4.mp4:
          uploadId: >-
            OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE
          parts:
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
        BZBW9RTSC95V94Z0XWFS0FGJS0.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
        BZBW9RTSC95V94Z0XWFS0FGJS0.mp4:
          uploadId: >-
            tZ20sgEAhQeApnMVW_yqg9j4swb3wKbE1DUo_FR64uQEy2DXrshomngSwPgPxj5wGjINj3AGU1ITHQ-hi4Z2FEXAMPLE
          parts:
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
        xxxxxxxxxxxxxxxxxxxxxx.json: https:xxxxxxxxxxxxxxxxxxxxxxxxx
        xxxxxxxxxxxxxxxxxxxxxx.mp4:
          uploadId: >-
            ud3N7J8YjCEW21dIC_OIe0WAjz4jvgjTVbAU_4Wnzy3TgGST5lSWpCQu4nm2gZqqc8cHx2WelIXqIS-essuHIEXAMPLE
          parts:
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
            - https:xxxxxxxxxxxxxxxxxxxxxxxxx
      additionalProperties:
        oneOf:
          - type: string
          - type: object
        description: |-
          発行した署名付きURL。
          キーは、Request bodyで指定したファイル名（`metaFile`、`jsonFile`、`movieFile.file`）とする。
          jsonファイルの場合、string型となり、発行した署名付きURLを格納する。
          動画ファイルの場合、object型となり、以下を格納する。
          - 署名付きURLのuploadId
          - Request bodyの`movieFile.splitted`の数、マルチパートの署名付きURL
    FileUploadPresignedURLRequest:
      title: FileUploadPresignedURLRequest
      type: object
      description: ファイルアップロード用署名付きURL取得（リクエスト）モデル
      example:
        deviceId: '123456789101234'
        applicationId: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
        dir: logs/abcxxxxxxxxxxxxx/
        file: hogehoge.log
      properties:
        deviceId:
          type: string
          description: THINKLETのIMEI NO
        applicationId:
          type: string
          description: アプリケーションID
        dir:
          type: string
          pattern: ^$|^((?!\.{1,2}/)[^/]+/)+$
          description: >-
            アップロード対象ファイルが格納されているディレクトリの相対パス（先頭に `/` を含まず、末尾に `/`
            を含む）。サブディレクトリが無い場合は空文字列。各セグメントに `.`・`..` 単体は使用不可
        file:
          type: string
          pattern: ^(?!\.{1,2}$)[^/]+$
          description: アップロード対象ファイルのファイル名。`.`・`..` 単体は使用不可
      required:
        - deviceId
        - applicationId
        - dir
        - 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: ファイルアップロード