Forge 改め、Autodesk Platform Services の Model Derivative API では、Model Derivative API：メタデータの活用 でご案内している方法を使用してメタデータを生成して JSON データとして参照することが出来るようになります。もちろん、Viewer 上での対話操作が必要な場面では、Forge Viewer：プロパティパネル のような情報の取得や表示も可能です。
もし、ユーザによる Viewer 上の対話操作なしにプログラムでメタデータを収集する際には、前者の方法が考えらえます。このとき、対象モデルが大規模なものだと、プロパティ JSON の生成やダウンロード、また、ダウンロード後の JSON から特定のプロパティを得るためのパース処理に時間がかかってしまいます。そこで、以前開催した Forge Data Days をはじめとした過去のイベントでは、クエリの方法を改善していく計画をご案内していました。
今回、この改善の一環として、ベータ版の新しいエンドポイントを導入しました。モデルのプロパティに対してより詳細なクエリを実行する POST {urn}/metadata/{modelGuid}/properties:queryです。このエンドポイントのサンプルは こちら、ソースコードは こちら から、それぞれご確認いただけます。
新しくリリースされたエンドポイントは、高度なクエリーオプションをサポートし、ページ分割された結果を返します。また、このエンドポイントでは、次のリクエストボディを指定することができます。
- pagination：レスポンスを複数のページに分割し、1 ページずつレスポンスを返す方法を指定します。limit 属性は、1 ページに含まれるオブジェクトの最大数を 20〜1000 個の範囲で指定します。offset 属性では、ページのプロパティ数を指定します。
- query：JSON 形式で定義されたカスタマイズしたクエリ DSL（Domain Specific Languages）です。条件を含む節を SQL 構文のような形式で定義します。いくつかの条件を指定することが出来ます。
- fields：オブジェクトのどのプロパティを返すかを指定します。この属性を指定しない場合、レスポンスはすべてのプロパティを返します。
- payload: レスポンスボディに含まれる数値の形式を指定します。既定値の text で文字列か、unit で ##<VALUE_OF_PROPERTY><UNIT_OF_VALUE><PRECISION><SYSTEM_UNIT> を指定することが出来ます。
今回は、query 属性をご紹介します。まず始めに、オブジェクト プロパティのサンプルを見てみましょう。
プロパティ内部では、ダイレクト カテゴリとして「Dimensions」、リーフプロパティとして「Area」を呼んでいます。また、直接の子プロパティとして、「バージョン」、「コンポーネント名」があります。なお、プロパティの値型は、基本的に複数のキーと値のペアがネストされたJSON である。特定のプロパティを見つけるには、properties.{category}.{property} のように JSON-path スタイルのキーを構成します。例えば、「Area」プロパティを参照するには、properties.Dimensions.Area と指定することが出来ます。 query は、基本属性、直接の子プロパティ、リーフプロパティによる検索に対応しています。
query では、条件にマッチする句を定義することが出来ます。この新しいエンドポイントは、$contains、 $gt、$between などのいくつかの条件(ルール)を受け入れます。 注意: 現在のリリースでは、リクエストボディに 1 つの句（1 つの条件）のみをサポートしています。
- $in： 特定のフィールドに対する正確な値のリストを含むリストクエリ句です。クエリ結果は、指定されたフィールドを含むオブジェクトを返し、フィールドの値は定義された値のいずれかと一致する必要があります。このリリースでは、基本属性である objectId （数値）と externalId（文字列） がサポートされています。例えば、以下のクエリは、値が123 または 789 であるオブジェクトを返します。
{
"$in": [
"objectid",
123,
789
]
}- $prefix：フィールドに特定のプレフィックス文字列を含むオブジェクトに一致するための句です(大文字小文字を区別しない)。基本的な name 属性のみがサポートされています。 例えば 名前が「System Panel」で始まるオブジェクトを検索する場合は、次のように定義します。
{
"$prefix": [
"name", 'System Panel'
]
}- $contains：特定のプロパティに対して複数の条件を指定します。結果は、指定されたフィールドを含むべきオブジェクトを返し、フィールドの値は定義された 1 つ以上の含むはずです（大文字小文字を区別しない）。各項目は、ASCII の空白文字で区切る必要があります。例えば、次の例では、”Aluminum Steel” というテキストマッチング・ルールは、別々の条件である Aluminum と Steel に変換されます。つまり、前述のクエリでは、プロパティ JSON がリーフプロパティ（Material）を含み、その値がサブストリング「Aluminum」または「Steel」、あるいはその両方を含むオブジェクトを返すことを意味します。
{
"$contains": [
"properties.Constrains.Material",
"Aluminum Steel"
]
}- $eq：この条件では、基本的な name 属性、またはユニットプロパティを受け入れます。name の場合は、その名前の文字列と完全に一致することを条件とします。
{
"$eq": [
"name ", “Door [
34567
]”
]
}unit プロパティの場合、2 つ目の値は数値である必要があります。さらに、値は常に統一された標準単位で、長さの単位はメートル（m）になります。ソース・モデルの正確な値がセンチメートル（cm）であると仮定すると、その値は 500 になりますが、$eq 句を使ってproperties.Constrains.height=500 のオブジェクトを探すには、標準単位（値=5）を使って検索する必要があります。
{
"$eq": [
"properties.Constrains.height",
5
]
}- $between：この条件は、単位プロパティのみを受け入れます。この条件では、値が 2 つの値の間にあるオブジェクトを返します（境界値も含まれます）。$eq と同様、標準単位で検索します。例えば、次の条件では、高さが 34.567 メートル以上、 123.789 メートル以下のオブジェクトを見つけます。
{
"$between": [
"properties.Constrains.height ",
34.567,
123.789
]
}- $le：unit プロパティのみを受け付けます。この条件では、値がある値より小さいオブジェクトを返します（境界の値も含まれます）。例えば、高さが 123.789 メートル以下のオブジェクトを検索します。
{
"$le": [
"properties.Constrains.height",
123.789
]
}- $ge：unit プロパティのみを受け付けます。この条件では、値がある値より小さいオブジェクトを返します（境界値も含まれます）。同じように、標準単位で検索します。例えば、高さが 34.567 メートル以下のオブジェクトを見つけます。
{
"$ge": [
"properties.Constrains.Length",
34.567
]
}内部メカニズムでは、すべての型のフィールドは、$contains に文字列インデックスを持ちます。元の型が数値の場合は、$le、$ge、$between、$eq にもインデックス付されます。
By Toshiaki Isezaki
Leave a Reply