BIM 360 Glue API
真正开发应用之前,使用工具来试调用RESTful API是必由之路,它可以帮助我们更加清晰直观的理解我们要使用的API。
下面我们用一个简单的例子来看看如何用cURL和PostMan(开发工具介绍)调用Glue API实现登录和查询工程的功能。
调用API登录
初次登录的时候,需要验证API秘钥(不清楚什么是API秘钥的可以看这里),验证成功之后服务器会返回一个auth_token,后续的操作可以不用用户名密码,而是用auth_token作代替。
登录命令是向https://b4.autodesk.com/api/security/v1/login.{format}地址发送POST请求,这里{format}指定了返回数据的格式,可以是json或xml两种,POST内容如下(还有其他没有列出的参数为可选):
参数 | 含义 |
login_name | 登录名,即Autodsek Id |
password | 登录密码 |
company_id | 公司ID |
api_key | API key |
api_secret | API secret |
timestamp | 时间戳,是一个用秒数表示的当前时间 |
sig | 一个md5码, 由api_key + api_secret + timestamp计算得出 |
上面的参数中最后两个,即timestamp和sig,一般需要用程序算出,几乎每个请求都要求这两个参数,而且它是随着时间变化而变化的。
它们的获取请参见我们后面的小节[获取timestamp和sig]。
这里我们使用json格式,所以,需要请求的url地址为:https://b4.autodesk.com/api/security/v1/login.json
方法是:POST
内容如下:
login_name=Aaron.Lu@autodesk.com
&company_id=adn
&password=********
&api_key=fe251558432bd3da0a70326ed169****
&api_secret=70aadb2838cac9a739da11296d7f****
×tamp=1428647796
&sig=6ec77c0448fcb16da9c1f03220a96ceb
使用cURL命令
在命令行中输入:
curl --data "login_name=Aaron.Lu@autodesk.com&company_id=adn&password=********&api_key=fe251558432bd3da0a70326ed169****&api_secret=70aadb2838cac9a739da11296d7f****&timstamp=1428647796&sig=6ec77c0448fcb16da9c1f03220a96ceb" https://b4.autodesk.com/api/security/v1/login.json
--data 指明要发送的数据,同时表明需要发送POST请求。
返回结果如下,是一段json格式的数据:
{"auth_token":"35730ba86d48470593c1e63090610aa5","user_id":"****0b93-e919-****-9695-8b3733fa****","account_id":"****a18f-****-4b8a-****-8d762595****","account_hostname":"adn"}
注意:记下auto_token,后面的请求都要用到它。
使用PostMan
选择方法为POST,在form-data中填上各个字段,点击”Send”,就可以在下方的Body栏看到同样的结果:
调用API获取项目列表
获取项目列表的url地址是https://b4.autodesk.com/api/project/v1/list.{format}
方法:GET
参数如下:
参数 | 含义 |
company_id | 公司ID |
api_key | API key |
timestamp | 时间戳,是一个用秒钟表示的当前时间 |
sig | 一个md5码, 由api_key + api_secret + timestamp计算得出 |
auth_token | 一个hash值,从登陆之后返回的一个字段中获取 |
可以看到api_secret, login_name, password字段已经不需要了,取而代之的是auth_token字段。
因为使用GET方法,参数都需要包含在url地址里,所以最终要访问的url地址就是:
使用cURL
在命令行中输入:
curl https://b4.autodesk.com/api/project/v1/list.json?company_id=adn&api_key=fe251558432bd3da0a70326ed169****×tamp=1428650893&sig=8d22b59569335394d7b219aae91990a7&auth_token=34dd71d838674c86a02da2fe329db24d
返回结果(用onlinejsonviewer美化之后):
{
"project_list": [
{
"recent_model_info": [],
"project_id": "1e7e5e8d-fea8-49cd-8e5b-76058f0ee3b6",
"project_name": "AL+Sample+Project",
"company_id": "adn",
"created_date": "2015-03-19 03:26:51",
"modify_date": "2015-04-01 07:15:15",
"cmic_company_code": "",
"cmic_project_code": "",
"cw_project_code": "",
"thumbnail_modified_date": "2015-03-19 04:41:45",
"has_views": false,
"has_markups": false,
"has_clashes": false,
"has_points": false,
"total_member_count": 0,
"total_project_admin_count": 0,
"total_views_count": 0,
"total_markups_count": 0,
"last_activity_date": "2015-04-01 07:15:15",
"permissions": [],
"navisworks_version": "Nwd2014"
}
],
"page": 1,
"page_size": 1,
"total_result_size": 1,
"more_pages": 0
}
使用PostMan
选择方法为GET,输入最终url地址,点击”Send”,结果就显示在界面下方。
程序计算timestamp和sig
timestamp
Timestamp是一个整形数字,表示的是当前时间(格林威治时间)相对于1970年1月1日0点所经过的时间的秒数值,叫做UNIXEpoch Time。伪代码可以表示如下:
秒数(当前时间-1970年1月1日0点)
下面是各平台获取该秒数的代码:
Powershell(Windows7自带命令行工具,比DOS要高级一点,在开始菜单输入PowerShell就能看到,由于我们用cURL命令行调用API,所以这里介绍命令行的方式获取我们需要的数据)
$oriDate=Get-Date -Date "01/01/1970"
$nowDate=(Get-Date).ToUniversalTime()
$timestamp=[int](New-TimeSpan -Start $oriDate -End $nowDate).TotalSeconds
C#
TimeSpan tSpan = (DateTime.UtcNow - new DateTime(1970, 1, 1));
int timestamp = (int)tSpan.TotalSeconds;
Node.js/Javascript
var timestamp = Math.floor((new Date).getTime()/1000);
Java
long timestamp = System.currentTimeMillis() / 1000L;
Ruby
timestamp = Time.now.getutc.to_i.to_s
sig
sig是md5码,GlueAPI要求的md5码是由api_key、auth_token和timestamp组成的字符串计算出来的md5码,另外必须是小写,且不带减号(-),其伪代码如下:
MD5 (api_key+api_secret+timestamp)
下面是各平台获取某个字符串MD5的代码:
Powershell
$identityString = $api_key + $api_secret + $timestamp
# compute hash
$md5 = new-object -TypeName System.Security.Cryptography.MD5CryptoServiceProvider
$utf8 = new-object -TypeName System.Text.UTF8Encoding
$signature = [System.BitConverter]::ToString($md5.ComputeHash($utf8.GetBytes($identityString))).Replace("-","").ToLower()
C#
// using System.Security.Cryptography;
var identityString = api_key + api_secret + timestamp;
public string ComputeMD5Hash(string identityString)
{
// step 1, calculate MD5 hash from identityString
MD5 md5 = System.Security.Cryptography.MD5.Create();
byte[] inputBytes = System.Text.Encoding.UTF8.GetBytes(identityString);
byte[] hash = md5.ComputeHash(inputBytes);
// step 2, convert byte array to hex string
StringBuilder sb = new StringBuilder();
for (int i = 0; i < hash.Length; i++)
{
sb.Append(hash[i].ToString("x2"));
}
return sb.ToString();
}
Node.js/Javascript
var crypto = require('crypto');
var hash = crypto.createHash('md5').update(identityString).digest("hex");
Java
public String computeMD5Hash(String identityString) {
java.security.MessageDigest md = java.security.MessageDigest.getInstance("MD5");
byte[] array = md.digest(identityString.getBytes());
StringBuffer sb = new StringBuffer();
for (int i = 0; i < array.length; ++i) {
sb.append(Integer.toHexString((array[i] & 0xFF) | 0x100).substring(1,3));
}
return sb.toString();
}
Ruby
require 'digest/md5'
Digest::MD5.hexdigest(api_key.api_secret.timestamp)
问题处理
如果碰到下面的情况可能的原因是使用的HTTP方法不对,例如,需要使用GET的时候,使用了POST或其他方法。
<body>
<div id="content">
<p class="heading1">Service</p>
<p>Method not allowed.</p>
</div>
</body>