本記事は 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」にデータを保存しておくことも出来ます。
実際にデータをアップロードしたりダウンロードしたりする作業は、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 の意味が次にように説明されているはずです（赤字）。
| Code | Message | Meaning |
|---|---|---|
| 200 | Ok | Successful retrieval of the hubs collection. |
| 401 | Unauthorized | The supplied Authorization header was not valid or the supplied token scope was not acceptable. Verify Authentication and try again. |
| 403 | Forbidden | The 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 アプリにアクセスを許可するための設定（アプリとの関連付け）方法をご紹介しておきいます。
- https://bim360docs.autodesk.com から BIM 360 Docs にサインインしたら、画面左の Document Management 左側のアイコンをクリックして Account Admin をクリックします。
- アカウント管理者 ページが表示されたら、次の図にある手順ように、画面上部の 「設定」 タブをクリックしてから [カスタム統合機能] タブを選択し、画面左下に表示される [カスタム統合機能を追加] ボタンをクリックします。[カスタム統合機能] タブが表示されない場合は、Forge アプリを BIM 360 と連携するための「カスタム統合機能」の注意点 の内容をご確認ください。
- アクセス権を指定して [次へ] をクリックします。
- 統合する Forge アプリを自身で開発するか、外部の開発者を招待するかを指定します。ここでは前者を選択したことにします。
- 次の画面で、Forge API を利用するアプリの登録とキーの取得 の手順でアプリ登録で取得した Client ID を入力して、画面下部の [保存] ボタンをクリックしてください。もちろん、BIM 360 Docs にアクセスする Forge アプリは、ここで関連付けた Client ID（Consumer Key）を利用して Access Token を得る必要があります。
- これで関連付けの設定は完了です。
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": []
}
]
}
}
なお、上記の例では、アカウント管理者によるアプリとの関連付けが終了しても、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
Subscribe
コメント