ZENKEI API リファレンス : チュートリアル

このチュートリアルでは、図面1つとポイント7つを持つプレイヤーを作成・公開するまでの流れを説明します。

画像はあらかじめご準備いただくか、こちらのサンプル素材(約5MB)をご利用ください。


■セッショントークンの取得

まず初めに、APIキー・アカウントID・パスワードを使用して、セッションを作成します。
これにより、以降の全てのメソッドの呼び出しで必要となるセッショントークンを取得できます。

リクエストURL
(POST) https://api.zenkei.biz/v2/session

リクエストヘッダ
X-ZENKEI-API-KEY:ZENKEI-REST-API-KEY

リクエストボディ
{
    "accountId":"zenkei-taro",
    "password":"Password1234"
}

レスポンスボディ
{
    "account":{
        "id":"zenkei-taro",
        "name":"全景 太郎",
        "teams":[
            {
                "id":"zenkei",
                "name":"全景株式会社",
                "dateExpire":"2016-08-01T09:00Z",
                "editionId":0,
                "canUseImages":true,
                "canUseFloorplans":true,
                "canUseScenes":true,
                "canUseAnnotations":true,
                "canUseWalkThroughs":true,
                "canUseMaps":true,
                "canSelectDesignGroups":true,
                "maxImagesCount":100,
                "maxXCount":1,
                "maxXPublishCount":1,
                "maxScenesCount":5,
                "maxAnnotationsCount":3,
                "lenses":[
                    {
                        "id":0,
                        "name":"RICOH THETA"
                    },
                    {
                        "id":1,
                        "name":"全天球"
                    }
                ],
                "designGroups":[
                    {
                        "id":0,
                        "name":"標準"
                    }
                ]
            }
        ]
    },
    "token":"9ea78538-442c-44b2-925c-8912da8462a6",
    "expires":"2016-07-01T10:00:00Z"
}

■画像のアップロード

プレイヤーに図面として登録する画像ファイル1枚、ポイントとして追加する画像ファイル7枚をアップロードします。

リクエストURL
(POST) https://api.zenkei.biz/v2/zenkei/images

リクエストヘッダ（※日本語のファイル名を指定する場合はURLエンコードが必要です。以下例のファイル名は「間取り図.jpg」）
Content-Disposition:attachment;Filename=%E9%96%93%E5%8F%96%E3%82%8A%E5%9B%B3.jpg
X-ZENKEI-SESSION-TOKEN:9ea78538-442c-44b2-925c-8912da8462a6

リクエストボディ
プレイヤーに図面として登録する画像ファイルのストリーム

レスポンスボディ
{
    "id":10000,
    "teamId":"zenkei",
    "name":"間取り図",
    "description":null,
    "format":"jpg",
    "lensId":-1,
    "latitude":null,
    "longitude":null,
    "altitude":null,
    "hasLocation":false,
    "fileSize": 32744,
    "width": 617,
    "height": 600,
    "registeredBy":"zenkei-taro",
    "modifiedBy":"zenkei-taro",
    "dateCreated":null,
    "dateRegistered":"2016-07-01T09:05:00Z",
    "dateModified":"2016-07-01T09:05:00Z",
    "datePublished":null,
    "isPublished":false,
    "isConverted":false,
    "tags":null,
    "url":null
}

上記は、プレイヤーに図面として登録する画像ファイルをアップロードする場合のリクエスト・レスポンス例です。
ポイントとして追加する画像7枚についても、それぞれ同様のリクエスト・レスポンスでアップロードします。
以降は、それら7枚の画像のIDを 10001～10007 として説明を続けます。

■図面用の画像の公開

次に、図面用の画像を公開します。
これは、公開中の画像のみがプレイヤーに登録できるためです。

リクエストURL
(PATCH) https://api.zenkei.biz/v2/zenkei/images/10000

リクエストヘッダ
X-ZENKEI-SESSION-TOKEN:9ea78538-442c-44b2-925c-8912da8462a6

リクエストボディ
{
    "isPublished":true
}

レスポンスボディ
{
    "id":10000,
    "teamId":"zenkei",
    "name":"間取り図",
    "description":null,
    "format":"jpg",
    "lensId":-1,
    "latitude":null,
    "longitude":null,
    "altitude":null,
    "hasLocation":false,
    "fileSize": 32744,
    "width": 617,
    "height": 600,
    "registeredBy":"zenkei-taro",
    "modifiedBy":"zenkei-taro",
    "dateCreated":null,
    "dateRegistered":"2016-07-01T09:05:00Z",
    "dateModified":"2016-07-01T09:07:00Z",
    "datePublished":"2016-07-01T09:07:00Z",
    "isPublished":true,
    "isConverted":false,
    "tags":null,
    "url":"https://images.zenkei.biz/zenkei/10000"
}

■ポイント用の画像の公開とパノラマ変換

図面用の画像と同様で、ポイント用の画像も公開します。
公開と同時にパノラマ変換も行います。
ここでは、全ての画像が RICOH THETA で撮影した画像であるとします。

リクエストURL
(PATCH) https://api.zenkei.biz/v2/zenkei/images/10001

リクエストヘッダ
X-ZENKEI-SESSION-TOKEN:9ea78538-442c-44b2-925c-8912da8462a6

リクエストボディ
{
    "lensId":0,
    "isPublished":true
}

レスポンスボディ
{
    "id":10001,
    "teamId":"zenkei",
    "name":"外観",
    "description":null,
    "format":"jpg",
    "lensId":0,
    "latitude":null,
    "longitude":null,
    "altitude":null,
    "hasLocation":false,
    "fileSize":2421884,
    "width":3584,
    "height":1792,
    "registeredBy":"zenkei-taro",
    "modifiedBy":"zenkei-taro",
    "dateCreated":null,
    "dateRegistered":"2016-07-01T09:10:00Z",
    "dateModified":"2016-07-01T09:15:00Z",
    "datePublished":"2016-07-01T09:15:00Z",
    "isPublished":true,
    "isConverted":true,
    "tags":null,
    "url":"https://images.zenkei.biz/zenkei/10001"
}

同様に他の6枚の画像についても、パノラマ変換と公開を行います。

■プレイヤーの作成

画像に関するステップは全て終わりました。
ここからはいよいよ、プレイヤーを作成・編集していきます。
このステップでは、プレイヤーの新規作成を行います。

リクエストURL
(POST) https://api.zenkei.biz/v2/zenkei/x

リクエストヘッダ
X-ZENKEI-SESSION-TOKEN:9ea78538-442c-44b2-925c-8912da8462a6

リクエストボディ
{
    "name":"新しいプレイヤー"
}

レスポンスボディ
{
    "id":100,
    "teamId":"zenkei",
    "name":"新しいプレイヤー",
    "description":null,
    "latitude":null,
    "longitude":null,
    "altitude":null,
    "hasLocation":false,
    "registeredBy":"zenkei-taro",
    "modifiedBy":"zenkei-taro",
    "dateRegistered":"2016-07-01T09:20:00Z",
    "dateModified":"2016-07-01T09:20:00Z",
    "datePublished":null,
    "isPublished":false,
    "designGroupId":0,
    "elements":null,
    "elementLinks":null,
    "tags":null,
    "url":null
}

■プレイヤーへの図面の登録

次に、プレイヤーに対して図面用の画像をプレイヤー要素として登録します。

リクエストURL
(POST) https://api.zenkei.biz/v2/zenkei/x/100/elements

リクエストヘッダ
X-ZENKEI-SESSION-TOKEN:9ea78538-442c-44b2-925c-8912da8462a6

リクエストボディ
{
    "role":"Floorplan",
    "name":"間取り図",
    "assetId":10000,
    "assetType":"Image",
    "properties":[
        {
            "name":"order",
            "value":0
        }
    ]
}

レスポンスボディ
{
    "id":1000,
    "role":"Floorplan",
    "name":"間取り図",
    "assetId":10000,
    "assetType":"Image",
    "asset":{
        "id":10000,
        "teamId":"zenkei",
        "name":"間取り図",
        "description":null,
        "format":"jpg",
        "lensId":-1,
        "latitude":null,
        "longitude":null,
        "altitude":null,
        "hasLocation":false,
        "fileSize": 32744,
        "width": 617,
        "height": 600,
        "registeredBy":"zenkei-taro",
        "modifiedBy":"zenkei-taro",
        "dateCreated":null,
        "dateRegistered":"2016-07-01T09:05:00Z",
        "dateModified":"2016-07-01T09:07:00Z",
        "datePublished":"2016-07-01T09:07:00Z",
        "isPublished":true,
        "isConverted":false,
        "tags":null,
        "url":"https://images.zenkei.biz/zenkei/10000"
    }
    "properties":[
        {
            "name":"order",
            "value":0
        }
    ]
}

■プレイヤーへのポイントの登録

次に、プレイヤーに対してポイント用の画像をプレイヤー要素として登録します。

リクエストURL
(POST) https://api.zenkei.biz/v2/zenkei/x/100/elements

リクエストヘッダ
X-ZENKEI-SESSION-TOKEN:9ea78538-442c-44b2-925c-8912da8462a6

リクエストボディ
{
    "role":"Scene",
    "name":"外観",
    "assetId":10001,
    "assetType":"Image"
}

レスポンスボディ
{
    "id":1001,
    "role":"Scene",
    "name":"外観",
    "assetId":10001,
    "assetType":"Image",
    "asset":{
        "id":10001,
        "teamId":"zenkei",
        "name":"外観",
        "description":null,
        "format":"jpg",
        "lensId":0,
        "latitude":null,
        "longitude":null,
        "altitude":null,
        "hasLocation":false,
        "fileSize":2421884,
        "width":3584,
        "height":1792,
        "registeredBy":"zenkei-taro",
        "modifiedBy":"zenkei-taro",
        "dateCreated":null,
        "dateRegistered":"2016-07-01T09:10:00Z",
        "dateModified":"2016-07-01T09:15:00Z",
        "datePublished":"2016-07-01T09:15:00Z",
        "isPublished":true,
        "isConverted":true,
        "tags":null,
        "url":"https://images.zenkei.biz/zenkei/10001"
    }
    "properties":null
}

他の6枚のポイント用画像についても、それぞれ同様のリクエスト・レスポンスでプレイヤーに登録します。
以降は、それら6つのプレイヤー要素のIDを 1002～1007 として説明を続けます。


他の6つのポイントについても、それぞれ同様のリクエスト・レスポンスで図面とリンク付けします。

■プレイヤーの公開

最後にプレイヤーを公開します。お疲れ様でした。

リクエストURL
(PATCH) https://api.zenkei.biz/v2/zenkei/x

リクエストヘッダ
X-ZENKEI-SESSION-TOKEN:9ea78538-442c-44b2-925c-8912da8462a6

リクエストボディ
{
    "isPublished":true
}

レスポンスボディ
{
    "id":100,
    "teamId":"zenkei",
    "name":"新しいプレイヤー",
    "description":null,
    "latitude":null,
    "longitude":null,
    "altitude":null,
    "hasLocation":false,
    "registeredBy":"zenkei-taro",
    "modifiedBy":"zenkei-taro",
    "dateRegistered":"2016-07-01T09:20:00Z",
    "dateModified":"2016-07-01T09:20:00Z",
    "datePublished":"2016-07-01T09:30:00Z",			
    "isPublished":true,
    "designGroupId":0,
    "elements":[
        {
            "id":1000,
            "role":"Floorplan",
            "name":"間取り図",
            "assetId":10000,
            "assetType":"Image",
            "asset":{
                "id":10000,
                "teamId":"zenkei",
                "name":"間取り図",
                "description":null,
                "format":"jpg",
                "lensId":-1,
                "latitude":null,
                "longitude":null,
                "altitude":null,
                "hasLocation":false,
                "fileSize": 32744,
                "width": 617,
                "height": 600,
                "registeredBy":"zenkei-taro",
                "modifiedBy":"zenkei-taro",
                "dateCreated":null,
                "dateRegistered":"2016-07-01T09:05:00Z",
                "dateModified":"2016-07-01T09:07:00Z",
                "datePublished":"2016-07-01T09:07:00Z",
                "isPublished":true,
                "isConverted":false,
                "tags":null,
                "url":"https://images.zenkei.biz/zenkei/10000"
            }
            "properties":[
                {
                    "name":"order",
                    "value":0
                }
            ]
        },
        {
            "id":1001,
            "role":"Scene",
            "name":"外観",
            "assetId":10001,
            "assetType":"Image",
            "asset":{
                "id":10001,
                "teamId":"zenkei",
                "name":"外観",
                "description":null,
                "format":"jpg",
                "lensId":0,
                "latitude":null,
                "longitude":null,
                "altitude":null,
                "hasLocation":false,
                "fileSize":2421884,
                "width":3584,
                "height":1792,
                "registeredBy":"zenkei-taro",
                "modifiedBy":"zenkei-taro",
                "dateCreated":null,
                "dateRegistered":"2016-07-01T09:10:00Z",
                "dateModified":"2016-07-01T09:15:00Z",
                "datePublished":"2016-07-01T09:15:00Z",
                "isPublished":true,
                "isConverted":true,
                "tags":null,
                "url":"https://images.zenkei.biz/zenkei/10001"
            }
            "properties":null
        },
        ～途中省略～
        {
            "id":1007,
            "role":"Scene",
            "name":"トイレ",
            "assetId":10005,
            "assetType":"Image",
            "asset":{
                "id":10005,
                "teamId":"zenkei",
                "name":"トイレ",
                "description":null,
                "format":"jpg",
                "lensId":0,
                "latitude":null,
                "longitude":null,
                "altitude":null,
                "hasLocation":false,
                "fileSize":2421884,
                "width":3584,
                "height":1792,
                "registeredBy":"zenkei-taro",
                "modifiedBy":"zenkei-taro",
                "dateCreated":null,
                "dateRegistered":"2016-07-01T09:14:00Z",
                "dateModified":"2016-07-01T09:15:00Z",
                "datePublished":"2016-07-01T09:15:00Z",
                "isPublished":true,
                "isConverted":true,
                "tags":null,
                "url":"https://images.zenkei.biz/zenkei/10007"
            }
            "properties":null
        }
    ],
    "elementLinks":[
        {
            "id":5000,
            "srcXElementId":1000,
            "dstXElementId":1001,
            "properties":[
                {
                    "name":"x",
                    "value":0.1
                },
                {
                    "name":"y",
                    "value":0.1
                },
                {
                    "name":"order",
                    "value":0
                },
                {
                    "name":"cameraOriginDirection",
                    "value":0.1
                }
            ]
        },
        ～途中省略～
        {
            "id":5006,
            "srcXElementId":1000,
            "dstXElementId":1007,
            "properties":[
                {
                    "name":"x",
                    "value":0.5
                },
                {
                    "name":"y",
                    "value":0.5
                },
                {
                    "name":"order",
                    "value":0
                },
                {
                    "name":"cameraOriginDirection",
                    "value":0.5
                }
            ]
        },
    ],
    "tags":null,
    "url":"https://x.zenkei.biz/zenkei/100"
}