アセット クエリ言語 (AQL) 構文を使用する
アセット クエリ言語 (AQL) は、1 つ以上のオブジェクトの検索クエリを作成するために Jira Service Management のアセットで使用される言語形式です。AQL によって、検索にあるアセットでオブジェクトまたはオブジェクトのグループを返して、オブジェクトの絞り込みや変更、カスタム フィールドの作成、自動化などを行えます。
AQL can be used in the Advanced AQL search, or within an Assets object custom field. This is one of Assets' most powerful and dynamic features.
基本的な構文
The basic syntax of an AQL query is <attribute> <operator> <value/function>. One or more objects is returned by the query when the attributes of these objects match the operator and value specified.
例: オーナー = “Ted Anderson”
この基本的な AQL クエリは、Owner が "Ted Anderson" であるすべてのオブジェクトを返します。値の名前にスペースがあるため、"Ted Anderson" は引用符で囲まれます。
特殊文字の構文
AQL には定義された構文があり、正確に入力する必要があります。
AQL では、大文字と小文字が区別されません。
値または属性にスペースが含まれている式を使用する場合は、上記の "Ted Anderson" の例のように、値を囲む引用符を含める必要があります。
If you are using an expression where the value or attribute contain quotation marks, you must escape the quotes by preceding them with backslashes. For example, if you have an object name such as 15" Screen, to search for it enter:
15\” ScreenAQL で指定する属性名は、アセット スキーマに存在する必要があります。そうでない場合、AQL は無効とみなされます。
AQL は次のタスクを実行する際に役立ちます。
ドット表記
ドット表記は、オブジェクトの参照チェーンを下に移動するために AQL で使用されます。フォーマット <attribute>.<attribute> <operator> <value/function> は、親オブジェクトで参照されるオブジェクトに基づく情報を返します。
例: “Belongs to Department”.Name = HR
この場合、Employeee オブジェクト タイプには「Belongs to Department」という参照属性があります。このクエリは、人事部門に属するすべての従業員を返します。
参照される属性にはスペースが含まれているため、二重引用符で囲まれています。
キーワード
You can use keywords in AQL to return one or more objects based upon properties of those objects instead of the object's attributes. The syntax looks like this: <keyword> <operator> <value/function>.
たとえば、objectType キーワードを使用すれば、特定のオブジェクト タイプのすべてのオブジェクトを返すことができます。次のテーブルでは、サポートされているキーワードとその例を示します。
キーワード | 説明 |
|---|---|
objectSchema | 検索結果を次のように特定のオブジェクト スキーマ名に制限できます。objectSchema = "ITSM Schema". |
objectSchemaId | 検索結果はオブジェクト スキーマ ID に制限できます。例:objectSchemaId in (1, 2). |
objectType | 検索結果は次のように特定のオブジェクト タイプ名に制限できます。objectType = "Employment Start Date". |
objectTypeId | 検索結果はオブジェクト タイプ ID に制限できます。例:objectTypeId in (1, 2). |
object | オブジェクトの検索は次のように制限できます。"object having inboundReferences()" では、インバウンド参照を持つすべてのオブジェクトを検索します。 |
objectId | 次のように、オブジェクト ID でオブジェクトを検索できます。"objectId = 114".オブジェクト ID はオブジェクトのキーにある番号ですが、プレフィックスがありません。たとえば、オブジェクトのキーが ITSM-1111 の場合、プレフィックスは ITSM でありオブジェクト IDは 1111 です。 |
"Host" オブジェクト タイプを持つすべてのオブジェクトを返す AQL クエリは次のとおりです。
objectType = "Host"Note: if you are in the Assets User role, you will not get to see the object type id and the schema id. You can get those values from your Assets Administrator or Assets Manager and then use it to perform AQL queries.
objectId ではなく、任意のオブジェクト タイプで Key 属性を使用すると特定のオブジェクトを検索できます。
例: Key="ITSM-1111" は、キーが ITSM-1111 である一意のオブジェクトを返します
演算子
演算子を使用すると、より詳細な論理式を作成できます。
次の表は、AQL でサポートされている演算子を示します。
演算子 | 説明 | AQL クエリの例 |
|---|---|---|
= | 大文字と小文字を区別しない値の等価テスト。 | Office = Stockholm Office 属性に、Stockholm または STOCKHOLM と等しい値があるかどうかを確認します。 |
== | 大文字と小文字を区別する値の等価テスト。 | Office==Stockholm Office 属性に、入力した大文字/小文字を考慮して Stockholm と等しい値があるかどうかを確認します。 |
!= | 不等式テスト | objecttype=Employee と Office!=Stockholm Employee オブジェクトに、値が Stockholm と等しくない属性 Office があるかどうかを確認します。 |
< | 指定の値より小さいかどうかのテスト。 | Price < 2000 Price が 2000 ドル未満かどうかを確認します。 |
> | 指定の値より大きいかどうかのテスト | Price > 2000 Price が 2000 ドルを超えているかどうかを確認します。 |
<= | 指定の値以下かどうかのテスト | Price <= 2000 Price が 2000 ドル以下かどうかを確認します。 |
>= | 指定の値以上かどうかのテスト | Price >= 2000 Price が 2000 ドル以上かどうかを確認します。 |
like | クエリ内の入力のサブセットと値を照合します。大文字と小文字は区別されません。 | objecttype=Employees と Office like Stock 'Stock' または 'STOCK' という文字を含む Office 属性値のある Employees type のオブジェクトを返します。 |
not like | クエリの入力のサブセットと一致する値を除外します。 | objecttype=Employees and Office not like Stock 「Stock」という文字を含まない Office 属性値のある Employees type のすべてのオブジェクトを返します。 |
in() | 指定された引数と一致するものを検索して、結果を返します。 | Office in (Stockholm, Oslo, "San Jose") Stockholm、Oslo、または San Jose のいずれかの値を持つ Office タイプのすべてのオブジェクトを返します。 |
not in() | 指定された引数との一致が見つかった結果を除外します。 | Office not in (Stockholm, Oslo, "San Jose") Stockholm、Oslo、または San Jose のいずれかの値を持たない Office タイプのすべてのオブジェクトを返します。 |
startswith | 値が指定された入力で始まる一致を検索します。大文字と小文字は区別されません。 | Office startsWith St 文字 "St" または "ST" で始まる Office タイプの値と一致する結果を返します。 |
endswith | 値が指定された入力で終わる一致を検索します。大文字と小文字は区別されません。 | Office endsWith St 文字「St」または「ST」で終わる Office タイプの値と一致する結果を返します。 |
is | 値が存在するかどうかをテストするのに役立ちます。 | Office is EMPTY Office タイプの値が存在するかどうかをチェックして、それに応じて結果を返します。 "Office is not EMPTY" Office タイプの値が空ではないかどうかを確認します。 |
dot operator(.) | オブジェクトの Referenced タイプ属性にナビゲートできます。 この演算子は一般に、次の場合に使用されます。 inboundReferences() または inR() 関数。 outboundReferences() または outR() 関数。 order by 句。 | Country.Office = Stockholm ここで、ドット演算子は属性 Country で参照されるオブジェクト Office に移動して、Office を値 Stockholm と比較します。 |
having | inboundReferences() または outboundReferences() 関数で使用 | object having inboundReferences() インバウンド参照を持つすべてのオブジェクトを返します。 |
not having | inboundReferences() または outboundReferences() 関数で使用 | object not having inboundReferences() インバウンド参照を持つすべてのオブジェクトを除外して、結果を返します。 |
組み合わせ演算子
AND/OR などの演算子によって、さらに大規模で複雑な AQL 式を作成できます。
この AQL クエリには、AND 演算子でリンクされた 2 つのステートメントが含まれています。
objectType = "Host" AND "Operating System" = "Ubuntu (64-bit"関数
複数の関数によって、AQL 式に動的な値を指定できます。
タイプ | 関数名 | 説明 |
|---|---|---|
日時 | now() | 幅広い関数を使用して、日時を含むクエリを記述できます。 m は分、h は時間、d は日数、w は週数をそれぞれ表します。 (例: Created > "now(-2h 15m)" のような条件のあるクエリは、2 時間と 15 分以内に作成されたすべてのオブジェクトを返します。 (例: 次のものを含むクエリ: objectType = Employees and "Employment End Date" < endOfMonth(-90d) は、Employment End Date が現在月の最終日までの 90 日間になるすべての Employee オブジェクトを返します。 (例: また、将来の日付を確認できます。たとえば、ソフトウェアのライセンスの有効期限が年末のいつまでに期限切れになるかを確認します。クエリは次のようにできます。licenseEndDate = endOfYear() 他のすべての日付関数も同様の方法で使用できます。 |
ユーザー
| currentUser() | AQL クエリでこの関数を呼び出すと、現在の (ログイン) ユーザーに接続されているユーザー属性をフィルタリングできます。クエリでフィルタリングに使用する属性は、User タイプである必要があります。 例: objecttype = Computer and User = currentUser() この関数は、CurrentUser が選択されている、つまりユーザーがログインしているときに機能します。 |
currentReporter() | AQL クエリでこの関数を呼び出すと、カスタム フィールドの現在の報告者に接続されているユーザー属性をフィルタリングできます。 クエリでフィルタリングに使用する属性は、User タイプである必要があります。 例: User = currentReporter() この関数は、課題が選択されている場合にのみ機能して、現在の課題に表示される報告者を参照します。 | |
user(user1, user2, ..) | 関数の引数リストで指定したユーザーへの参照を持つオブジェクトをフィルタリングできます。フィルタリングに使用する属性は、User タイプである必要があります。 この関数は、フィルタリングする User タイプ属性が複数の値を許可する場合、つまりこのカーディナリティが複数の場合のみ、複数の引数で機能します。 (例: オブジェクト タイプ Team には属性 Member があります。この属性は User タイプです。さらに、この属性のカーディナリティは 3 と設定されています。ユーザー admin と manager がメンバーである一連の Team オブジェクトを検索する場合は、以下のクエリを記述できます。 objecttype=Team and Member having user("admin", "manager") | |
グループ | group(group1, group2,...) | 特定のグループ内のユーザーに接続されている任意のオブジェクトをフィルタリングできます。フィルタリングに使用する属性は、User タイプである必要があります。 例: User in group("jira-users", "jira-administrators") |
| user(user1, user2, ...) | 特定のグループ内のユーザーに接続されている任意のオブジェクトをフィルタリングします。フィルターに使用する属性は、Group タイプである必要があります。 例 Group having user("currentReporter()") |
Project | currentProject() | 現在選択されている Jira プロジェクトに接続されているオブジェクトを絞り込みます。チケットのコンテキスト内でのみ機能します。 例: Project = currentProject() |
参照関数
参照関数は、AQL や参照型引数の 2 つの引数を取る関数です。基本的に、参照関数によって、特定の参照タイプを持つオブジェクトのサブセットに対して AQL クエリを実行できます。このようなクエリはオブジェクト合計数が小さいサブセットで実行することで、結果や処理時間を制限できます。
The AQL argument can be an arbitrary AQL including an AQL with a reference function.
参照型引数はオプションです。
シリアル番号 | 名前 | 説明 |
|---|---|---|
a |
| インバウンド参照のあるオブジェクトをフィルタリングします。この参照オブジェクトは、関数への引数として提供された AQL クエリに一致するものです。 e.g. An AQL query like: object having inboundReferences() will return all objects having inbound references since the empty AQL argument to the function will match all inbound referenced objects. ただし、object having inboundReferences(Name="John") のようなクエリの例では、属性 Name があり Name の値が「John」のようなインバウンド参照オブジェクトのあるすべてのオブジェクトを返します。 |
B |
| これは、(a) で説明されている inboundReferences(AQL) 関数から派生したものです。 これを使用すると、参照タイプを 1 つ以上の値として指定することによって、インバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。 参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [追加値 (Additional Value)] フィールドです。 e.g. An AQL query like this: object having inR(objectType = "File System", refType IN ("Depends")) 「File System」というインバウンド参照オブジェクトがあり、その File System オブジェクトの参照タイプが 「Depends」であるオブジェクトを返します。 Similarly, an AQL query like: object having inR(objectType = "File System", refType IN ("Depends", "Installed", "Using")) File System というインバウンド参照オブジェクトがあり、その File System オブジェクトの参照タイプが Depends、Installed、Using のいずれかであるオブジェクトを返します。 |
c |
| アウトバウンド参照のあるオブジェクトをフィルタリングします。この参照オブジェクトは、関数への引数として提供された AQL クエリに一致するものです。 e.g. An AQL query like: object having outboundReferences() will return all objects having outbound references since the empty AQL argument to the function will match all outbound referenced objects. ただし、bject having outboundReferences(Name="John") のようなクエリの例では、属性 Name があり、Name の値が "John" のようなアウトバウンド参照オブジェクトのあるすべてのオブジェクトを返します。 |
d |
| これは、(b) で説明されている outboundReferences(AQL) 関数から派生したものです。 これを使用すると、参照タイプを 1 つ以上の値として指定することによって、アウトバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。 参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [追加値 (Additional Value)] フィールドです。 e.g. An AQL query like this: object having outR(objectType = "Employees", refType IN ("Location")) アウトバウンド参照オブジェクト Employees があり、その Employees オブジェクトの参照タイプが "Location" であるオブジェクトを返します。 Similarly, an AQL query like: object having outR(objectType = "Employees", refType IN ("Location", "Country")) アウトバウンド参照オブジェクト Employees があり、その Employees オブジェクトの参照タイプが Location, Country のいずれかであるオブジェクトを返します。 |
connectedTickets() 関数の使用
The connectedTickets() function is used to filter objects having tickets connected to them. Specific Jira issues may be selected by providing a proper Jira Query Language (JQL) query. If no JQL query is provided, all objects having Jira issues connected are returned. You must provide a JQL as an argument to that AQL function (e.g. object having connectedTickets(Project = VK)).
ConnectedTickets () 関数は Confluence のアセット・マクロでは動作しません。Confluence でのアセット・データ表示の詳細をご確認ください。
名前 | 説明 |
|---|---|
connectedTickets(JQL query) | 指定の JQL クエリに一致するチケットが接続されているオブジェクトが返されます。 たとえば、クエリ: object HAVING connectedTickets(labels is empty) は JQL クエリ (labels is empty) を接続されているすべてのチケットで実行して、その結果に基づいてオブジェクトを返します。 |
objectTypeAndChildren() 関数を使用する
この関数は、特定のオブジェクト タイプのオブジェクト (およびその子) を返すために使用されます。
名前 | 説明 |
|---|---|
objectTypeAndChildren(Name) | Name とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。名前にスペースが含まれている場合は、必ず二重引用符で囲んでください。 |
objectTypeAndChildren(ID) | ID とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。 |
この AQL クエリは "Asset Details" オブジェクト タイプからのすべてのオブジェクトと子オブジェクトを返します。
objectType in objectTypeAndChildren("Asset Details") 参照、関数、AQL を組み合わせる
関数、参照、AQL は、さまざまな優れた方法で組み合わせられます。たとえば、あるオブジェクトに添付されている 1 つのカスタム フィールドに複数のオブジェクト参照を追加して、これらの参照を次のような特定のキーで検索できます。
object HAVING inboundReferences(Key IN (${MyCustomField${0}}))
または、ドット表記を使用して次のような特定のラベルで検索できます。
object HAVING inboundReferences(Label IN (${Portfolios.label${0}}))
注: 上記の 2 つのクエリでは、アセット プレースホルダーが使用されます。アセット プレースホルダーの詳細についてご確認ください。
これらの関数は、正式な名前 (inboundReferencs) を使用するか略称 (inR) として書き出せます。その動作は同じです。
この強力な関数を使用すると、特に否定を使用するなど複雑なクエリが構築された場合に、一見明らかではない結果が生成される可能性があることにご注意ください。これを解釈するには、クエリを 2 つのステップ アクションとして考える必要があります。
JQL 実行
JQL 結果で動作する AQL 実行
The Assets Object Detail View presents Unresolved connected tickets by default.
発注
任意の AQL に次のサフィックスを追加すると、クエリの結果を並べ替えられます。
order by [AttributeName|label] [asc|desc]
order by 句を指定しない場合、デフォルトはオブジェクト タイプの labe 属性によって昇順になります。
order by 句で指定された属性がオブジェクト参照タイプである場合は、ドット表記によって参照オブジェクトの属性で並べ替えられます。Employee オブジェクトの参照 Department オブジェクトで並べ替える場合は、order by Employee.Department のように句を記述できます。この操作の深度は無制限です。ただし、order by 句のすべてのドットは、その特定の AQL のパフォーマンス低下の原因になることに注意してください。
見つからない値はリストの上部に表示されます。これは、クエリ内の順序が昇順である場合に true になります: "asc"。
AQL で指定された属性名は、アセットに存在する必要があります。そうでない場合、AQL は無効とみなされます。属性の名前を入力する際は、大文字と小文字のどちらでも使用できます。
結果に「order by」句で指定された属性が含まれていない場合、返されるオブジェクトの順序は任意になります。
属性名の代わりにプレースホルダー ラベルを使用して、設定されたラベルでオブジェクトを並べ替えられます。
複数の属性による順序づけはサポートされていません。
この内容はお役に立ちましたか?