Aras Innovator 11 SP12は、Arasアイテムを検索したり編集したりするのに使えるRESTful APIを導入しました。多くの場合、外部アプリやシステム連携でこれらのRESTコールを使うことができます。Aras Labs GitHubページ上で、この新Aras RESTful APIを使用したサンプルAngularJS app を見つけることもできますが、今回のブログ投稿では、人気のAPI開発環境 Postmanを使用して共通のREST呼び出しを行ってみます。Postmanは、一切コードを書かずにAPI呼び出しを試せる便利ツールです。
RESTコールのセットアップ
Aras Innovatorに対するAPIコールを成功させるには、４つの重要な情報が必要です。１つ目は、あなたのInnovatorインスタンスのODataサービス：http://{server}/{web alias}/server/odata に対するURLです。簡単に言うと、これはこのAPI呼び出しの“ベースURL”と言えます。
次に、APIコールのリクエストを認証するために以下のヘッダーを含める必要があります。
- DATABASE: 接続先のAras Innovatorデータベース名
- AUTHUSER: 接続に使用するAras Innovator ユーザ名
- AUTHPASSWORD: AUTHUSERで指定したユーザのMD5ハッシュ化パスワード
Postmanの“Headers”タブで、送信するリクエストにこれらのヘッダーを追加できます。
上図スクリーンショットは、Postmanクライアント上で入力した必須ヘッダーの様子を示します。
重要な注意点!
リクエストヘッダーで使用されるAUTHUSERは、Aras Innovatorに対するユーザパーミッションを評価する時に使用されます。AUTHUSERが参照や編集のパーミッションを持たないアイテムを検索または編集しようとすると、API呼び出しのレスポンスで、エラー、もしくは、“No items of type {ItemType} found”を受け取るでしょう。同様に、このブログで示すように、rootやadminユーザをハードコードしてしまうと、必ずしも全ユーザが取得、編集すべきでないデータをうっかりと人目にさらしてしまうかもしれません。
アイテムの取得
最も簡単なGETコールは、あるアイテムタイプの全アイテムを取得します。例えば、GETリクエスト：http://{server}/{web alias}/server/odata/Partで、全パーツを取得できます。
URL: http://{server}/{web alias}/server/odata/PartのODataリクエストを送信し、全パーツを取得します。
もちろん、いつもアイテムタイプの全アイテムのすべてのプロパティを取得したいというわけではありません。アイテムデータを検索する方法がいくつか用意されています。
ID指定で１つのアイテムを取得する
GET {base url}/Part(‘F45F259F527942EB8A6C4011BC784EF0’)
{
"@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part/$entity",
"classification": "Component",
"created_on": "2018-03-20T19:37:02",
"description": "Part 2 description",
"generation": "1",
"has_change_pending": "0",
"id": "F45F259F527942EB8A6C4011BC784EF0",
"is_current": "1",
"is_released": "0",
"keyed_name": "P-00002",
"major_rev": "A",
"make_buy": "Make",
"modified_on": "2018-03-20T19:37:02",
"name": "Part 2",
"new_version": "0",
"not_lockable": "0",
"state": "Preliminary",
"unit": "EA",
"item_number": "P-00002"
}
条件を指定した検索
GET {base url}/Part?$filter=item_number eq ‘P-00001’
{
"@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part",
"value": [
{
"classification": "Component",
"created_on": "2018-03-20T19:36:06",
"description": "Part 1 description",
"generation": "1",
"has_change_pending": "0",
"id": "FE186527EB6B40079EE0334AD47B353A",
"is_current": "1",
"is_released": "0",
"keyed_name": "P-00001",
"major_rev": "A",
"make_buy": "Make",
"modified_on": "2018-03-20T19:36:06",
"name": "Part 1",
"new_version": "0",
"not_lockable": "0",
"state": "Preliminary",
"unit": "EA",
"item_number": "P-00001"
}
]
}
レスポンスで返すプロパティを限定
GET {base url}/Part?$select=id,item_number,name
{
"@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part(id,item_number,name)",
"value": [
{
"id": "FE186527EB6B40079EE0334AD47B353A",
"item_number": "P-00001",
"name": "Part 1"
},
{
"id": "F45F259F527942EB8A6C4011BC784EF0",
"item_number": "P-00002",
"name": "Part 2"
},
{
"id": "16AA95A80DEB4B56BD8BA9BC509EAF0C",
"item_number": "P-00033",
"name": "Part 3"
},
{
"id": "836DB08EB33D412EB662D75934CADCF1",
"item_number": "Part-00005",
"name": "Test Part 5"
}
]
}
結果アイテムの件数を取得
GET {base url}/Part/$count
4
プロパティ値を取得
GET {base url}/Part(‘F45F259F527942EB8A6C4011BC784EF0’)/item_number/$value
P-00002
アイテムプロパティのデータを取得
GET {base url}/Part(‘F45F259F527942EB8A6C4011BC784EF0’)?$expand=created_by_id&$select=item_number
{
"@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part(item_number)/$entity",
"@odata.id": "Part('F45F259F527942EB8A6C4011BC784EF0')",
"item_number": "P-00002",
"created_by_id": {
"created_on": "2002-04-24T13:46:12",
"generation": "1",
"id": "30B991F927274FA3829655F50C99472E",
"is_current": "1",
"is_released": "0",
"keyed_name": "Innovator Admin",
"last_login_date": "2018-03-22T12:56:04",
"login_name": "admin",
"logon_enabled": "1",
"major_rev": "A",
"modified_on": "2004-01-16T20:18:31",
"new_version": "0",
"not_lockable": "0",
"state": "Released",
"working_directory": "C:",
"first_name": "Innovator",
"last_name": "Admin"
}
}
リレーションシップ／リレーティッドアイテムの取得
GET {base url}/Part(‘C3F13FE4A2674B9691A6B311B5CCBCDB’)/Part CAD?$expand=related_id
{
"@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part CAD",
"value": [
{
"behavior": "hard_fixed",
"created_on": "2018-03-26T21:23:54",
"generation": "1",
"id": "A732D5425B0F4362BA48062BACA1C7F4",
"is_current": "1",
"is_released": "0",
"keyed_name": "A732D5425B0F4362BA48062BACA1C7F4",
"major_rev": "A",
"modified_on": "2018-03-26T21:23:54",
"new_version": "1",
"not_lockable": "0",
"related_id": {
"created_on": "2018-03-26T21:23:30",
"generation": "1",
"has_change_pending": "0",
"id": "B1ABC9872FF2440A9909E9D34A5AF363",
"is_current": "1",
"is_released": "0",
"is_standard": "0",
"is_template": "0",
"keyed_name": "CAD-00002",
"major_rev": "A",
"modified_on": "2018-03-26T21:23:30",
"name": "CAD for P-00002",
"new_version": "1",
"not_lockable": "0",
"state": "Preliminary",
"item_number": "CAD-00002"
},
"sort_order": "128"
}
]
}
アイテムの作成
Aras Innovatorにアイテムを新規作成するには、“POST” HTTPアクションを使用し、リクエストBodyの中に新規アイテムのプロパティを含めます。
“POST” HTTPアクションとリクエストのBody内に必須プロパティを含めて新規パーツを作成します。
アイテムの新規作成
POST {base url}/Part
Body:
{
"item_number": "Part-00005",
"name": "Test Part 5"
}
Result:
{
"@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part/$entity",
"created_on": "2018-03-20T20:24:49",
"generation": "1",
"has_change_pending": "0",
"id": "836DB08EB33D412EB662D75934CADCF1",
"is_current": "1",
"is_released": "0",
"keyed_name": "Part-00005",
"major_rev": "A",
"make_buy": "Make",
"modified_on": "2018-03-20T20:24:49",
"name": "Test Part 5",
"new_version": "0",
"not_lockable": "0",
"state": "Preliminary",
"unit": "EA",
"item_number": "Part-00005"
}
プロパティ内にアイテムを新規作成（ディープインサート）
POST {base url}/Part
Body:
{
"item_number": "Part-00006",
"name": "Test Part 6",
"owned_by_id":
{
"name": "New Identity"
}
}
Response:
{
"@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part/$entity",
"created_on": "2018-03-26T21:45:28",
"generation": "1",
"has_change_pending": "0",
"id": "8CAD376AC9284307A1299695FAC40F8F",
"is_current": "1",
"is_released": "0",
"keyed_name": "Part-00006",
"major_rev": "A",
"make_buy": "Make",
"modified_on": "2018-03-26T21:45:29",
"name": "Test Part 6",
"new_version": "0",
"not_lockable": "0",
"owned_by_id": {
"created_on": "2018-03-26T21:45:29",
"generation": "1",
"id": "41D69C4C75BF4512942E0368385B3A26",
"is_alias": "0",
"is_current": "1",
"is_released": "0",
"keyed_name": "New Identity",
"major_rev": "A",
"modified_on": "2018-03-26T21:45:29",
"new_version": "1",
"not_lockable": "0",
"name": "New Identity"
},
"state": "Preliminary",
"unit": "EA",
"item_number": "Part-00006"
}
アイテムの更新
To update an Aras item, use the “PATCH” HTTP action and include any properties you want to update in the body of the request. Be sure only to include updatable properties, or the request will fail.
Updating Part number P-00033 to fix the item_number property.
アイテムの更新
PATCH {base url}/Part(’16AA95A80DEB4B56BD8BA9BC509EAF0C’)
Body:
{
"item_number": "Part-00003"
}
Response:
{
"@odata.context": "http://localhost/FedSP12/server/odata/$metadata#Part/$entity",
"classification": "Assembly",
"created_on": "2018-03-20T19:37:43",
"description": "Part 3 description",
"generation": "2",
"has_change_pending": "0",
"id": "7F7556DE8ED642A6BE78C43259A00087",
"is_current": "1",
"is_released": "0",
"keyed_name": "Part-00003",
"major_rev": "A",
"make_buy": "Make",
"modified_on": "2018-03-26T21:51:58",
"name": "Part 3",
"new_version": "0",
"not_lockable": "0",
"state": "Preliminary",
"unit": "EA",
"item_number": "Part-00003"
}
さらなるアイディアを求めて
さらなるお役立ち情報をお求めの場合は、私たちのブログを購読し、ツイッターで@ArasLabsをフォローしてください。Aras Labs GitHubページで私たちの最新のオープンソースプロジェクトやサンプルコードを見つけることもできます。