Autodesk Developer Blog

Innovate. Integrate. Automate

BIM 360 Docs と Data Management API アクセス

—

by

Toshiaki Isezaki
in

本記事は BIM 360 Docs のユーザ インタフェース変更に伴い、タブ名や画像を一部改定しています（2018年3月16日）

以前、Forge が使用するクラウド ストレージ でご案内したとおり、Forge アプリが 3-legged 認証でユーザからクラウド  ストレージへのアクセス認可が得られると、取得した Access Token でユーザのストレージ領域にアクセスすることが出来るようになります。この方法で、A360、A360 Team や BIM 360 Team、Fusion Team、また、BIM 360 Docs のユーザ ストレージにアクセスしながら、データ連携する独自の Forge アプリを開発することが可能になります。

もちろん、2-legged 認証を利用することで、クラウド サービスのユーザ ストレージではなく、アプリ独自の領域「Bucket」にデータを保存しておくことも出来ます。 

BIM 360 Docsのクラウドサービスの構造を示すフローチャート。2-legged認証と3-legged認証の流れを解説し、HubやProject、Item、Versionなどの要素をビジュアルで表現。

実際にデータをアップロードしたりダウンロードしたりする作業は、Data Management API の各種 endpoint を使用することになります。このとき、操作対象となるデザイン ファイル（ Item や Version）のドキュメント ID（URN）が判明していない限り、オートデスク クラウド サービスに共通する論理構造を上位から、Hub >> Project >> Folder >> Item >> Version の順で追跡して目的のデザイン ファイル（ないし、そのバージョン）を見出す必要があります。

そのような場面では、最初に Hub からアクセスしていくことになります。例えば、Forge アプリにアクセス認可を与えたユーザが、BIM360 Team（A360 Team、Fusion Team 同等）、A360 Personal（無償）、BIM 360 Docs に関連付けられている場合には、endpoint https://developer.api.autodesk.com/project/v1/hubs、メソッド GET を使って関連付けられた Hub のリストを取得することが出来ます。ところが、実際に取得した JSON レスポンスは、次の赤字部分のように BIM 360 Docs の Hub 情報がエラーになって取得出来ていない可能性があります。ここでは、分かりやすくするために、それぞれの Hub 情報の当該コープ冒頭にクラウド サービスのアイコンを配置しています。

{
    "jsonapi": {
        "version": "1.0"
    },
    "links": {
        "self": {
            "href": "https://developer.api.autodesk.com/project/v1/hubs"
        }
    },
    "data": [
        {
            "type": "hubs",
            "id": "a.YnVzaW5lc3M6bXlpMzYy",
            "attributes": {
                "name": "俊明 伊勢崎",
                "extension": {
                    "type": "hubs:autodesk.core:Hub",
                    "version": "1.0",
                    "schema": {
                        "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.core:Hub-1.0"
                    },
                    "data": {}
                }
            },
            "links": {
                "self": {
                    "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6bXlpMzYy"
                }
            },
            "relationships": {
                "projects": {
                    "links": {
                        "related": {
                            "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6bXlpMzYy/projects"
                        }
                    }
                }
            }
        },
        {
            "type": "hubs",
            "id": "a.cGVyc29uYWw6dWUyOWM4M2Jm",
            "attributes": {
                "name": "Toshiaki Isezaki",
                "extension": {
                    "type": "hubs:autodesk.a360:PersonalHub",
                    "version": "1.0",
                    "schema": {
                        "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.a360:PersonalHub-1.0"
                    },
                    "data": {}
                }
            },
            "links": {
                "self": {
                    "href": "https://developer.api.autodesk.com/project/v1/hubs/a.cGVyc29uYWw6dWUyOWM4M2Jm"
                }
            },
            "relationships": {
                "projects": {
                    "links": {
                        "related": {
                            "href": "https://developer.api.autodesk.com/project/v1/hubs/a.cGVyc29uYWw6dWUyOWM4M2Jm/projects"
                        }
                    }
                }
            }
        }
    ],
    "meta": {
        "warnings": [
            {
                "Id": null,
                "HttpStatusCode": "403",
                "ErrorCode": "BIM360DM_ERROR",
                "Title": "Unable to get hubs from BIM360DM US.",
                "Detail": "You don't have permission to access this API",
                "AboutLink": null,
                "Source": [],
                "meta": []
            },
            {
                "Id": null,
                "HttpStatusCode": "403",
                "ErrorCode": "BIM360DM_ERROR",
                "Title": "Unable to get hubs from BIM360DM EMEA.",
                "Detail": "You don't have permission to access this API",
                "AboutLink": null,
                "Source": [],
                "meta": []
            }
        ]
    }
}

エラーコードを表わす “HttpStatusCode” の値 “403” と、エラー詳細を表わす “Detail” の値 “You don’t have permission to access this API” でもお分かりのとおり、BIM 360 Docs のストレージにアクセスする十分な権限がないのがエラーの原因です。endpoint https://developer.api.autodesk.com/project/v1/hubs リファレンス ページにには、エラーコード 403 の意味が次にように説明されているはずです（赤字）。

CodeMessageMeaning
200OkSuccessful retrieval of the hubs collection.
401UnauthorizedThe supplied Authorization header was not valid or the supplied token scope was not acceptable. Verify Authentication and try again.
403ForbiddenThe request was successfully validated but permission is not granted or the application has not been white-listed. Do not try again unless you solve permissions first.

実は、Forge アプリが BIM 360 Docs のストレージ領域にアクセスするには、 BIM 360 Docs のアカウント管理者による設定が必要なのです。ここでは、アカウント管理者が Forge アプリにアクセスを許可するための設定（アプリとの関連付け）方法をご紹介しておきいます。

  1. https://bim360docs.autodesk.com から BIM 360 Docs にサインインしたら、画面左の Document Management 左側のアイコンをクリックして Account Admin をクリックします。
  2. アカウント管理者 ページが表示されたら、次の図にある手順ように、画面上部の 「設定」 タブをクリックしてから [カスタム統合機能] タブを選択し、画面左下に表示される [カスタム統合機能を追加] ボタンをクリックします。[カスタム統合機能] タブが表示されない場合は、Forge アプリを BIM 360 と連携するための「カスタム統合機能」の注意点 の内容をご確認ください。
  3. アクセス権を指定して [次へ] をクリックします。
  4. 統合する Forge アプリを自身で開発するか、外部の開発者を招待するかを指定します。ここでは前者を選択したことにします。
  5. 次の画面で、Forge API を利用するアプリの登録とキーの取得 の手順でアプリ登録で取得した Client ID を入力して、画面下部の [保存] ボタンをクリックしてください。もちろん、BIM 360 Docs にアクセスする Forge アプリは、ここで関連付けた Client ID（Consumer Key）を利用して Access Token を得る必要があります。
  6. これで関連付けの設定は完了です。

Forge アプリが 5.で指定した Client ID と対をなす Client Secret を利用していれば、下記青字のように BIM 360 Docs の Hub 情報を JSON で得られるはずです。

{
    "jsonapi": {
        "version": "1.0"
    },
    "links": {
        "self": {
            "href": "https://developer.api.autodesk.com/project/v1/hubs"
        }
    },
    "data": [
        {
            "type": "hubs",
            "id": "a.YnVzaW5lc3M6bXlpMzYy",
            "attributes": {
                "name": "俊明 伊勢崎",
                "extension": {
                    "type": "hubs:autodesk.core:Hub",
                    "version": "1.0",
                    "schema": {
                        "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.core:Hub-1.0"
                    },
                    "data": {}
                }
            },
            "links": {
                "self": {
                    "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6bXlpMzYy"
                }
            },
            "relationships": {
                "projects": {
                    "links": {
                        "related": {
                            "href": "https://developer.api.autodesk.com/project/v1/hubs/a.YnVzaW5lc3M6bXlpMzYy/projects"
                        }
                    }
                }
            }
        },
        {
            "type": "hubs",
            "id": "a.cGVyc29uYWw6dWUyOWM4M2Jm",
            "attributes": {
                "name": "Toshiaki Isezaki",
                "extension": {
                    "type": "hubs:autodesk.a360:PersonalHub",
                    "version": "1.0",
                    "schema": {
                        "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.a360:PersonalHub-1.0"
                    },
                    "data": {}
                }
            },
            "links": {
                "self": {
                    "href": "https://developer.api.autodesk.com/project/v1/hubs/a.cGVyc29uYWw6dWUyOWM4M2Jm"
                }
            },
            "relationships": {
                "projects": {
                    "links": {
                        "related": {
                            "href": "https://developer.api.autodesk.com/project/v1/hubs/a.cGVyc29uYWw6dWUyOWM4M2Jm/projects"
                        }
                    }
                }
            }
        },
        {
            "type": "hubs",
            "id": "b.a4f95080-84fe-4281-8d0a-bd8c885695e0",
            "attributes": {
                "name": "Autodesk2016-02-01 22:47:50 UTC",
                "extension": {
                    "type": "hubs:autodesk.bim360:Account",
                    "version": "1.0",
                    "schema": {
                        "href": "https://developer.api.autodesk.com/schema/v1/versions/hubs:autodesk.bim360:Account-1.0"
                    },
                    "data": {}
                }
            },
            "links": {
                "self": {
                    "href": "https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c885695e0"
                }
            },
            "relationships": {
                "projects": {
                    "links": {
                        "related": {
                            "href": "https://developer.api.autodesk.com/project/v1/hubs/b.a4f95080-84fe-4281-8d0a-bd8c885695e0/projects"
                        }
                    }
                }
            }
        }
    ],
    "meta": {
        "warnings": [
            {
                "Id": null,
                "HttpStatusCode": "403",
                "ErrorCode": "BIM360DM_ERROR",
                "Title": "Unable to get hubs from BIM360DM EMEA.",
                "Detail": "You don't have permission to access this API",
                "AboutLink": null,
                "Source": [],
                "meta": []
            }
        ]<
/span>
    }
}

なお、上記の例では、アカウント管理者によるアプリとの関連付けが終了しても、Hub の取得に成功するのは US（米国）のデータセンターを用いている BIM 360 Docs のみです。EMEAのデータセンターを利用する BIM 360 Docs の Hub 情報はエラーのままです。（EMEA は Europe、the Middle East、Africa の略ですが、実質ヨーロッパを指します）。

BIM 360 Docs の契約時には、利用するストレージを持つデータセンターの場所を、US と EMEA の 2 箇所から 1 つを選択指定するが出来ます。このエラーは、選択しなかったデータセンターにはアクセスが出来ないために発生するものです。

つまり、ここでご紹介した BIM 360 Docs は、US のデータセンターを使用するようセットアップされているため、EMEA データセンターへのアクセスでエラーになっています。ですので、ここでは無視していただいても構いません。

ここまでアクセス出来れば、Postman による Viewer 利用手順の理解 – 3 legged 認証 にある手順で、特定のデザイン ファイル（Item ないし、そのVersion）にアクセスすることが出来るはずです。

By Toshiaki Isezaki

Discover more from Autodesk Developer Blog

Subscribe now to keep reading and get access to the full archive.

Continue reading