章節四 Forge OAuth、Forge 服務整體及 SDK 簡介

Forge OAuth

OAuth 是什麼

OAuth 是一種開放授權標準、是一種 OpenID 的擴充，允許用戶讓第三方應用透過權杖(Access Token) 在特定時間內（如一個小時內）存取該用戶在某一網站上儲存受保護的資源（如相片，影片，聯絡人列表），而無需將用戶名稱和密碼提供給第三方應用的一種授權機制 (Ref: Wikipedia)，像 Amazon、Google、Facebook、Microsoft、Twitter 等公司都透過此機制讓用戶授權給其他網站或應用程式存取他們的資料，同時相關公司也成立 OAuth 討論群組主導這個開放標準的制定。

OAuth 目前最新的版本是 OAuth 2.0，並支援下面4種授權流程：

  1. Authorization Code Grant Type Flow

  2. Implicit Grant Type Flow

  3. Resource Owner Password Credentials Grant Type Flow

  4. Client Credentials Grant Type Flow

Autodesk Forge OAuth 服務

Autodesk Forge 亦透過 OAuth 來保護用戶存放在 Forge 平台上的模型資料及 Autodesk 雲端產品 (例如 BIM360、A360、BIM360 Team、Fusion360 等) 的數據資料，以及確保有授權的第三方應用程式、網站才可以上傳資料或檔案到 Forge 雲端服務平台上，同時依據使用場景分成下列兩種：

兩條腿 (2-Legged Context):

這種授權場景使用 Client Credentials Grant Type Flow 這種授權流程，讓第三方應用程直接與 Forge 平台發出請求以取得存取儲存於 Forge 平台上的資料的權限，其工作流程是：

  1. 你的應用程式呼叫 POST authenticate 端點，並傳入你的 Client ID 和 Client Secret 以取得 Access Token

  2. 取得 Access Token後，可以將此 Token 使用在標示 app only 或 user context optional 的 Forge APIs，例如：

三條腿(2-Legged Context):

這種授權場景裡，第三方應用程式需要導引用戶登入他們的 Autodesk帳號，此場景拿到的 Access Token 只可以用在標示 user context required 或 user context optional 的 Forge APIs上，其主要用來存取該帳號放在 Autodesk 雲端產品 (例如 BIM360、A360、BIM360 Team、Fusion360 等) 上的數據資料，並可依據換取 Access Token 的方式分為下面兩種：

簡化的流程圖

Note. 想要了解上面內容的更多細節可以參考 Autodesk Forge 官網的 API Basics

Forge 服務簡介及使用示範

Data Management API

Data Management API 提供了一個統一的資料存取模式，用來存取 Autodesk 雲端產品 (例如 BIM360、A360、BIM360 Team、Fusion360 等) 上的資料，以及底層資料存儲服務（OSS，Object Storage Service），依 API 用途簡單分類為下面兩種：

Data Management API for BIM360:

主要用來存取 Autodesk 雲端產品 (例如 BIM360、A360、BIM360 Team、Fusion360 等) 上的資料，其功能有：

OSS (Object Storage Service):

主要用來上傳/下載檔案及開發者自己的檔案管理，在這個服務裡我們主要面對的是資料容器 (Bucket) 以及容器資料 (Object、上傳的檔案) 的存取，且依 Bucket 的擁有者可以分為下面兩種：

Model Derivative API (本次學習目標)

Model Derivative API 支援將近 60 餘種業界常見的模型格式、檔案轉檔為其他格式，和截取檔案中的模型資料、清單文件，其功能包含：

-將部份支援檔案從原始格式轉檔成一些通用格式，例如 STL、STEP、.IGES 及 OBJ 等

BIM360 API

前面提到的 Data Management API 是用來管理模型檔案資料而存在的 API，而BIM360 API 是專門用來管理、存取 BIM360 軟體平台資料存在的 API，其功能包含：

Design Automation API

Design Automation API 是一組可以用來協助設計自動化流程的 API，可以想像成 Autodesk 把自己的設計軟體如 AutodCAD, Revit, Inventor 和 3ds Max 等放在雲端，讓使用者在不用安裝、開啟相關軟體的情況下也能體驗到相關軟體帶來的好處；以 Revit 為例，我們可以透過 Design Automation API for Revit 做到：

Reality Capture API

Reality Capture API 是一組用於照片建模 API，支援將空拍機或是手提攝影機所產出的照片處理成點雲、3D Meshes 和正射影相。

Viewer API (本次學習目標)

Forge Viewer 又稱 Large Model Viewer，是基於 three.js 開發的 JavaScript 程式庫，可以用來在網頁裡瀏覽、檢視、協作多種二維 (2D) 或三維 (3D) 的模型，並開放豐富的應用介面 (API) 來發展、擴充自有應用，其功能包含：

3D模型

2D模型

Viewer 前處理工作流程圖

alt Forge Viewer Work Flow

Viewer 前處理工作流程 API呼叫範例

  1. 取得權杖 (Access Token)

     curl -v 'https://developer.api.autodesk.com/authentication/v1/authenticate'
   -X 'POST'
   -H 'Content-Type: application/x-www-form-urlencoded'
   -d '
     client_id=YOUR_FORGE_CLIENT_ID&
     client_secret=YOUR_FORGE_CLIENT_SECRETE&
     grant_type=client_credentials&
     scope=viewable:read
   '

  2. 上傳模型

     curl -v 'https://developer.api.autodesk.com/oss/v2/buckets/YOUR_BUCKET_NAME/objects/adsk-forge-helloworld.rvt'
   -X 'PUT'
   -H 'Authorization: Bearer YOUR_FORGE_ACCESS_TOKEN'
   -H 'Content-Type: application/octet-stream'
   -T 'adsk-forge-helloworld.rvt'

  3. 送出轉檔工作

     curl -X 'POST' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -H 'Authorization: Bearer YOUR_FORGE_ACCESS_TOKEN'
     -v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/job' \
     -d
       '{
         "input": {
           "urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6WU9VUl9CVUNLRVRfTkFNRS9hZHNrLWZvcmdlLWhlbGxvd29ybGQucnZ0"
         },
         "output": {
           "formats": [
             {
               "type": "svf",
               "views": [
                 "2d",
                 "3d"
               ]
             }
           ]
         }
       }'

  4. 取得轉檔進度

     curl -X 'GET' \
     -H 'Authorization: Bearer YOUR_FORGE_ACCESS_TOKEN' \
     -v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6WU9VUl9CVUNLRVRfTkFNRS9hZHNrLWZvcmdlLWhlbGxvd29ybGQucnZ0/manifest'

Forge Client SDK 簡介

除了上面提到的使用 curl 命令列工具 (Command-line interface，CLI) 的方式外，還可以透過各程式語言的 HTTP client 來呼叫 Forge 平台的 (REST style) Web API，且為了方便開發人員快速的整合 Forge REST API 到你的應用程式裡，針對不同程式語言提供了 Forge Client SDK 。

支援的 Client SDK 套件

.NET SDK 使用範例 (以Viewer 前處理工作流程為例)

1.取得權杖 (Access Token)

    var scopes = new Scope[] {
      Scope.DataRead,
      Scope.DataWrite,
      Scope.DataCreate
    };
    var oauth = new TwoLeggedApi();
    string grantType = "client_credentials";

    dynamic bearer = await oauth.AuthenticateAsync(
      "YOUR_FORGE_CLIENT_ID",
      "YOUR_FORGE_CLIENT_SECRET",
      grantType,
      scopes
    );

2.上傳模型

  var objects = new ObjectsApi();
  objects.Configuration.AccessToken = bearer.access_token;

  dynamic uploadedObj;
  using( StreamReader streamReader = new StreamReader( fileSavePath ) )
  {
    uploadedObj = await objects.UploadObjectAsync(
      "YOUR_BUCKET_NAME",
      "adsk-forge-helloworld.rvt",
      (int)streamReader.BaseStream.Length,
      streamReader.BaseStream,
      "application/octet-stream"
    );
  }

3.送出轉檔工作

  List<JobPayloadItem> outputs = new List<JobPayloadItem>()
  {
    new JobPayloadItem(
      JobPayloadItem.TypeEnum.Svf,
      new List<JobPayloadItem.ViewsEnum>()
      {
        JobPayloadItem.ViewsEnum._2d,
        JobPayloadItem.ViewsEnum._3d
      }
    )
  };

  var job = new JobPayload(
    new JobPayloadInput( "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6WU9VUl9CVUNLRVRfTkFNRS9hZHNrLWZvcmdlLWhlbGxvd29ybGQucnZ0" ),
    new JobPayloadOutput( outputs )
  );

  // start the translation
  var derivative = new DerivativesApi();
  derivative.Configuration.AccessToken = bearer.access_token;
  dynamic jobPosted = await derivative.TranslateAsync(job);

4.取得轉檔進度

  var derivative = new DerivativesApi();
  derivative.Configuration.AccessToken = bearer.access_token;
  dynamic manifest = derivative.GetManifest( "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6WU9VUl9CVUNLRVRfTkFNRS9hZHNrLWZvcmdlLWhlbGxvd29ybGQucnZ0" );


回到首頁