メタデータの取得例

このセクションでは、エンティティとフィールドのメタデータにアクセスしてALM Octane REST APIを操作する方法の例を示します。

ユーザーストーリーエンティティのメタデータを取得する

リクエスト

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/entities?query="name EQ 'story'"

応答

{
  "data": [
    {
      "features": [
        {
          "methods": [
            "DELETE",
            "POST",
            "GET",
            "PUT"
          ],
          "name": "rest",
          "url": "stories"
        },
        {
          "name": "mailing",
          "url": "mails"
        },
        {
          "name": "phases"
        },
        {
          "name": "subtype_of",
          "type": "work_item"
        },
        {
          "parent_types": [
            "feature",
            "work_item_root"
          ],
          "max_depth": 4,
          "root": {
            "type": "work_item_root",
            "id": "1001"
          },
          "name": "hierarchy",
          "child_types": []
        },
        {
          "name": "user_defined_fields"
        },
        {
          "name": "business_rules"
        },
        {
          "name": "comments",
        },
        {
          "name": "attachments",
        }
      ],
      "name": "story",
      "description": null,
      "label": "Story",
      "type": "entity_metadata"
    }
  ],
  "total_count": 1
}

応答の説明

この例をワークスペースレベルで見てみましょう。この例から、次のことがわかります。

説明 メタデータの抜粋
ユーザーストーリーに対してDELETE、POST、GET、およびPUT操作を実行できます。
{
  "features": [
    {
      "methods": [
         "DELETE",
         "POST",
         "GET",
         "PUT"
       ],
      "name": "rest",
         "url": "stories"
},                      

ユーザーストーリーは階層的です。

彼らの「親」は作業項目です。

ユーザーストーリーのルート項目のIDは1001です。

彼らには「子供」がいません。

{
  "parent_types": [
     "feature",
     "work_item_root"
   ],
  "max_depth": 4,
  "root": {
     "type": "work_item_root",
     "id": "1001"
    },
  "name": "hierarchy",
     "child_types": []
},

定義されたワークフローを使用して、エンティティのステータスをフェーズからフェーズに進める機能がサポートされています。

エンティティのフェーズの変更は、エンティティ自体で実行されます。たとえば、エンティティのフェーズ (またはステータス) を変更するには、エンティティに対してPUTを実行します。

{
  "name": "phases"
},
ユーザーストーリーは、作業項目のサブタイプです。
{
          "name": "subtype_of",
          "type": "work_item"
        },

ユーザーストーリーエンティティは以下をサポートします。

  • ユーザー定義フィールドの作成。

  • グループ化、および標準設定の順序を設定する機能。

  • エンティティの電子メール。

  • User-definedタグ付け。

  • 添付ファイル。

  • ルールを使用したワークフローのカスタマイズ。

  • コメント。

  • ordering属性を使用してユーザーストーリーをランク付けする機能。

    制限事項:  作業項目のランク付けは、PUTリクエストを使用してサポートされます。GETリクエストでの作業項目のランクの取得はサポートされておらず、nullが返されます。

{
   "name": "phases"
},
{
   "name": "subtype_of",
   "type": "work_item"
},
{
   "name": "user_defined_fields"
},
{
   "name": "default_order_by",
   "field_name": "name",
   "direction": "ASC"
},
{
   "name": "ordering",
   "aspects": [{
      "aspect_name": "rank",
      "order_field_name": "rank",
      "context_field_name": null
      }
     ]
},
{
   "name": "mailing",
   "url": "mails"
},
{
   "name": "has_user_tags"
},
{
   "name": "attachments","
},
{
    "name": "business_rules"
},
{
    "name": "comments",
}

トップに戻る

パイプラインのフィールドメタデータを取得する

パイプラインのワークスペースレベルの例を次に示します。

リクエスト

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ 'pipeline'"

トップに戻る

結果の説明

説明 メタデータ
パイプラインフィールドには、ID、パイプライン名、作成時間、パイプラインのルートジョブ、バージョンスタンプ、作成者、および現在のリリースが含まれます。
"name": "id",
"name": "name",
"name": "creation_time",  
"name": "version_stamp",
"name": "author",
"name": "last_modified",
"name": "current_release",

以下を含む (ただしこれらに限定されない) 各パイプラインフィールドに関する情報を表示できます。

  • フィールドの名前。

  • エンティティの名前。

  • フィールドの説明。

  • フィールドのラベル。通常、ALM Octane UIでの表示に使用されます。

  • フィールドの値のタイプ (文字列、date_time)。

{
  "entity_name": "pipeline",
  "description": "",
  "label": "Creation time",
  "name": "creation_time",
   "field_type": "date_time",
},

フィールドがエンティティコレクションを参照していることを示します。

参照情報: Reference

 

"field_type_data": {
    "multiple": false,
    "targets": [
       {
         "type": ""workspace_user"
       }
     ]
},

Sanitization

フィールドがサニタイズをサポートしている場合。

REST API出力サニタイズは、リクエストによって返されたデータを削除またはエンコードします。これにより、セキュリティリスクが軽減されます。参照情報: Sanitization

有効なサニタイズタイプは次のとおりです。 

  • NONE。値を「そのまま」返します。ほとんどのフィールドはサニタイズされていません。

  • HTML。事前定義されたHTMLサニタイズ許可リストに従って値を返します。この許可リストを使用して、 Memo-type

{
  "sanitization": "NONE"
},
フィールドが履歴目的の追跡などの追加フィーチャー /フィーチャーをサポートしている場合。この場合、機能はauditableと呼ばれます。
"field_features": [
   {
     "name": "auditable"
   }
 ],

フィールドが最終的な場合。

エンティティの作成時にのみ、値をフィールドに指定できます。その後、フィールドは読み取り専用になります。

Authorフィールドは、finaltrueに設定するのに適した候補です。

参照情報:  Final

                                    {
  "final": true
},
                                

パイプラインフィールドが次のいずれかであるかどうかを判断できます。

  • グループ化、フィルタリング、および並べ替えに使用できます。

  • 編集できます。

  • ユーザー定義です。

  • 必要とされている。

  • ルールで使用されます。

  • 一意である必要があります。

  • ALM Octane UIに表示されます。

 

{
  "filterable": true,
  "editable": false,
  "label": "Creation time",
  "sortable": true,
  "is_user_defined": false,
  "required": false,
  "accessible_via_business_rules": true,
  "unique": false,
  "name": "creation_time",
  "groupable": false,
  "visible_in_ui": true
},		

トップに戻る

エンティティに必要なフィールドを知る

REST APIを使用して新しいエンティティを作成する場合、どのフィールドが必須であるかを事前に知っておくと役立ちます。required属性を使用します。

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ 'defect'; required EQ 'true'"

トップに戻る

GET操作で標準設定で返されないフィールドを確認する

標準設定で返されないフィールドのリストを表示するには、フィールドメタデータをクエリして、returned_by_default属性を確認します。 

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="returned_by_default EQ false"

トップに戻る

エンティティフィールドに許可されている値を取得する

一部のエンティティはリストに関連付けられています。たとえば、実行はステータスに関連付けられています。ストーリー、不具合、要件などの他のエンティティは、フェーズに関連付けられています。

Skippedは、自動テスト実行では有効なステータスである可能性がありますが、手動テスト実行では有効ではありません。

In Designは要件に対して有効なフェーズである可能性がありますが、不具合に対しては有効ではありません。

新しいエンティティを作成するときは、これらが必須フィールドであるため、正しいステータスまたはフェーズを指定する必要があります。

このトピックでは、フィールドメタデータとlist_nodeリソースコレクションを使用して、エンティティに関連する値を取得する方法について説明します。list_nodeリソースコレクションにはすべてのリスト値が含まれ、それらを関連するエンティティにマップします。

手動テスト実行のステータスの有効な値を取得します

フィールドメタデータを使用すると、手動実行のすべてのフィールドとそのプロパティを確認できます。 

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ ^run_manual^"

手動テスト実行の2つのステータスフィールドが表示されます。 

  • list_node.native_status、その説明は「計画済み、合格、失敗、未完了、ブロックなどの実行のステータス」です。

  • list_node.run_status、その説明は「合格、失敗、注意が必要など、実行の集約されたステータス」です。このステータスは、ダッシュボードなどの分析目的でネイティブステータスを要約するために使用されます。

これらのステータスの両方の値は、logical_name属性を使用して、リストノードへのターゲット参照として保存されます。

list_node.native_status

      "field_type_data": {
        "multiple": false,
        "targets": [
          {
            "logical_name": "list_node.run_native_status",
            "type":  "list_node"
          }
        ]
      }, 

list_node.run_status

      "field_type_data": {
        "multiple": false,
        "targets": [
          {
            "logical_name": "list_node.run_status",
            "type": "list_node"
          }
        ]
      },

手動実行のネイティブステータスに許可される値を確認するには、list_nodesリソースコレクションで、論理名プレフィックスlist_node.run_native_statusに基づいたステータスを確認します。ワイルドカード*を使用して、このプレフィックスが付いたすべてのステータスを一覧表示します。

GET .../api/shared_spaces/<space_id>/works/<workspace_id>list_nodes?query="logical_name EQ ^ list_node.run_native_status*^"

これで、手動実行の許可されたステータスが表示されます。これは、たとえば、RESTAPIを使用して新しい手動テスト実行をPOSTするときに割り当てることができます。ステータスは、passedfailedblockedskippedcompletedplannedです (および1つのroot list_node)。

{
  "total_count": 7,
  "data": [
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.passed",
      "version_stamp": 1,
      "name": "Passed",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1092",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.failed",
      "version_stamp": 1,
      "name": "Failed",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1091",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.blocked",
      "version_stamp": 1,
      "name": "Blocked",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1094",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.skipped",
      "version_stamp": 1,
      "name": "Skipped",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1090",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.not_completed",
      "version_stamp": 1,
      "name": "Not Completed",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1093",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.planned",
      "version_stamp": 1,
      "name": "Planned",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1095",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status",
      "version_stamp": 1,
      "name": "Run_Native_Status",
      "list_root": null,
      "id": "1089",
      "last_modified": "2017-05-09T19:05:51Z"
    }
  ],
  "exceeds_total_count": false
}

トップに戻る

エンティティのコメントを見る

パフォーマンスを最適化するために、エンティティをGETする場合、コメントは応答に含まれません。コメントを表示するには、fields句を使用してコメントを明示的にリクエストする必要があります。

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects&fields=comments

トップに戻る

特定のバージョンの非推奨のAPIリソースを取得する

ALM Octaneの新しいバージョンにアップグレードした後、廃止されたリソースのリストを表示したい場合があります。非推奨になったときにこれらのリソースがサポートされなくなった場合に備えて、代わりに対応するエイリアスを参照するようにコードを更新することをお勧めします。

非推奨のリソースを確認するには、deprecatedフィールドでクエリを実行し、アップグレードしたバージョン番号を指定します。

非推奨のリソースの例:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="deprecated EQ ^12.55.8^"

ヒント: 非推奨のリソースのエイリアスを確認するには、インタラクティブAPIクライアントを使用します。詳細については、インタラクティブAPIクライアントを参照してください。

トップに戻る

参照情報: