詳細検索: AQL - アセット クエリ言語
AQL (アセット クエリ言語) は、アセットで 1 つ以上のオブジェクトの検索クエリを作成するための言語形式です。AQL によって、アセットで任意のオブジェクトまたはオブジェクトのグループを検索で返す、オブジェクトを絞り込む、オブジェクトを変更する、カスタム フィールドを作成するといった操作や、自動化、事後操作などを行えます。
基本的な構文
AQL クエリの基本的な構文は、<attribute> <operator> <value/function> です。これらのオブジェクトの属性が指定の演算子と値と一致すると、クエリによって 1 つ以上のオブジェクトが返されます。
例
- 基本的な AQL クエリは Owner が "Jennifer Evans" であるすべてのオブジェクトを返します。値の名前にスペースがあるため "Jennifer Evans" を囲んでいる引用符は必要です。
特殊文字の構文
AQL には定義された構文があり、正確に入力する必要があります。
- AQL では、大文字と小文字が区別されます。
- 値または属性にスペースが含まれている式を使用する場合は、「Ted Anderson」の例のように値を囲む引用符を含める必要があります。
- 値または属性に引用符が含まれている式を使用する場合は、引用符をバックスラッシュで囲んでエスケープする必要があります。たとえば、15" Screen のような名前のオブジェクトがある場合は、検索時に "15\" Screen" と入力します。
- AQL で指定する属性名は、アセット スキーマに存在する必要があります。そうでない場合、AQL は無効とみなされます。属性名では大文字と小文字が区別されます。
ドット表記
ドット表記は、オブジェクトの参照チェーンを下に移動するために AQL で使用されます。フォーマット <attribute>.<attribute> <operator> <value/function> は、親オブジェクトで参照されるオブジェクトに基づく情報を返します。
例
- この場合、Employee オブジェクト タイプには "Belongs to Department" という参照属性があります。このクエリは "Management" 部門に属するすべての従業員を返します。
- 参照される属性にはスペースが含まれているため、二重引用符で囲まれています。
キーワード
AQL でキーワードを使用すると、オブジェクトの属性ではなくオブジェクトのプロパティに基づく 1 つ以上のオブジェクトを返せます。その構文は <keyword> <operator> <value/function> のようになります。
たとえば、objectType キーワードを使用して特定のオブジェクト タイプのすべてのオブジェクトを、anyAttribute キーワードを使用して特定の属性を持つタイプのすべてのオブジェクトを返せます。次の表では、サポートされているキーワードとその例について説明します。
| キーワード | 説明 |
|---|---|
| objectType | 検索結果は特定のオブジェクト タイプ名に制限できます (例: objectType = "Employment Start Date")。属性にはスペースが含まれているため、二重引用符で囲まれています。 |
| objectTypeId | 検索結果はオブジェクト タイプ ID に制限できます。例: objectTypeId in (1, 2) |
| anyAttribute | すべてのオブジェクトのすべての属性で、関連する一致を検索できます。例: "anyAttribute = 123.123.123.123" このキーワードによって検索結果に遅延が生じる場合があります。アセットのインストール サイズが大きくなるほど、このキーワードによるクエリの実行にかかる時間が長くなります。 |
| オブジェクト | オブジェクトの検索は次のように制限できます。"object having inboundReferences()" では、インバウンド参照を持つすべてのオブジェクトを検索します。 |
| objectId | オブジェクトをオブジェクト ID で検索できます (例: "objectId = 114")。オブジェクト ID はオブジェクトのキーにある番号ですが、プレフィックスがありません。たとえば、オブジェクトのキーが ITSM-1111 の場合、プレフィックスは ITSM でオブジェクト IDは 1111 です。スキーマ全体でオブジェクトを移動するとキーが変更される可能性があることにご注意ください。 |
例
- "Computers" オブジェクト タイプを持つすべてのオブジェクトを返す AQL クエリは、次のとおりです。
演算子
演算子を使用すると、より詳細な論理式を作成できます。
次の表は、AQL でサポートされている演算子を示します。
| 演算子 | 説明 | AQL クエリの例 |
|---|---|---|
| = | 大文字と小文字を区別しない値の等価テスト。 | "Office = Stockholm" Office 属性に、Stockholm または STOCKHOLM と等しい値があるかどうかを確認します。 |
| == | 大文字と小文字を区別する値の等価テスト。 | "Office==Stockholm" Office 属性に、入力した大文字/小文字を考慮して Stockholm と等しい値があるかどうかを確認します。 |
| != | 不等式テスト | objecttype=Employee and Office!=Stockholm Employee オブジェクトに、値が Stockholm と等しくない属性 Office があるかどうかを確認します。 |
| < | 指定の値より小さいかどうかのテスト。 | "Price < 2000" Price が 2000 ドル未満かどうかをチェックします。 |
| > | 指定の値より大きいかどうかのテスト | "Price > 2000" Price が 2000 ドルを超えているかどうかをチェックします。 |
| <= | 指定の値以下かどうかのテスト | "Price <= 2000" Price が 2000 ドル以下かどうかを確認します。 |
| >= | 指定の値以上かどうかのテスト | "Price >= 2000" Price が 2000 ドル以上かどうかをチェックします。 |
| いいね！ | クエリ内の入力のサブセットと値を照合します。大文字と小文字は区別されません。 | "objecttype=Employees and 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()" インバウンド参照を持つすべてのオブジェクトを除外して、結果を返します。 |
例
- IN 演算子と objectType によって 3 つの異なるオブジェクト タイプのオブジェクトを返す AQL クエリ。
組み合わせ演算子
AND/OR などの演算子を使用すると、さらに大規模で複雑な AQL 式を作成できます。
例
- AND 演算子でリンクされた 2 つのステートメントを含む AQL クエリ
関数
複数の関数を使用して、AQL 式に動的な値を指定できます。
| タイプ | 関数名 | 説明 |
|---|---|---|
| 日付 | now() startOfDay() endOfDay() startOfWeek() endOfWeek() startOfMonth() endOfMonth() startOfYear() endOfYear() | 幅広い関数を使用して、日時を含むクエリを記述できます。 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() 他のすべての日付関数も同様の方法で使用できます。 |
| IP アドレス | CIDR(IP RANGE) | CIDR(IP RANGE) - IP 範囲でのフィルター 例: |
| ユーザー | 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()") | |
| プロジェクト | currentProject() | 現在選択されている Jira プロジェクトに接続されているオブジェクトを絞り込みます。チケットのコンテキスト内でのみ機能します。 例: Project = currentProject() |
参照関数
参照関数は、AQL や参照型引数の 2 つの引数を取る関数です。基本的に、参照関数を使用すると、特定の参照タイプのオブジェクトのサブセットに対して AQL クエリを実行できます。このようなクエリはオブジェクト合計数が小さいサブセットで実行することで、結果や処理時間を制限できます。
- AQL 引数には、参照関数を持つ AQL を含む任意の AQL を指定できます。
- 参照型引数はオプションです。
| シリアル番号 | 名前 | 説明 |
|---|---|---|
| a |
| インバウンド参照のあるオブジェクトをフィルタリングします。この参照は関数への引数として提供された AQL クエリに一致するものです。 例:object having inboundReferences() のような AQL クエリは、関数に対する空の AQL 引数がすべてのインバウンド参照オブジェクトと一致するため、インバウンド参照のあるすべてのオブジェクトを返します。 ただし、object having inboundReferences(Name="John") のようなクエリの例では、属性 Name があり Name の値が「John」のようなインバウンド参照オブジェクトのあるすべてのオブジェクトを返します。 |
| B |
| これは、(a) で説明されている inboundReferences(AQL) 関数から派生したものです これを使用すると、参照タイプを 1 つ以上の値として指定することによって、インバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。 参照タイプは、オブジェクト タイプの参照オブジェクトを定義する際に属性に指定する [さらなるメリット] フィールドです (以下スクリーンショット参照)。
例:object having inR(objectType = "File System", refType IN ("Depends")) のような AQL クエリは 「File System」というインバウンド参照オブジェクトがあり、その File System オブジェクトの参照タイプが 「Depends」であるオブジェクトを返します。 同様に、object having inR(objectType = "File System", refType IN ("Depends", "Installed", "Using")) のような AQL クエリは File System というインバウンド参照オブジェクトがあり、その File System オブジェクトの参照タイプが Depends、Installed、Using のいずれかであるオブジェクトを返します。 |
| c |
| アウトバウンド参照のあるオブジェクトをフィルタリングします。この参照は、関数への引数として提供された AQL クエリに一致するものです。 例:object having outboundReferences() のような AQL クエリは関数への空の AQL 引数がすべてのアウトバウンド参照オブジェクトと一致するため、アウトバウンド参照のあるすべてのオブジェクトを返します。 ただし、bject having outboundReferences(Name="John") のようなクエリの例では、属性 Name があり、Name の値が "John" のようなアウトバウンド参照オブジェクトのあるすべてのオブジェクトを返します。 |
| d |
| これは、(b) で説明されている outboundReferences(AQL) 関数から派生したものです。 これを使用すると、参照タイプを 1 つ以上の値として指定することによって、アウトバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。 参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [さらなるメリット (Additional Value)] フィールドです。 例:object having outR(objectType = "Employees", refType IN ("Location")) のような AQL クエリは アウトバウンド参照オブジェクト Employees があり、その Employees オブジェクトの参照タイプが "Location" であるオブジェクトを返します。 同様に、object having outR(objectType = "Employees", refType IN ("Location", "Country")) のような AQL クエリは アウトバウンド参照オブジェクト Employees があり、その Employees オブジェクトの参照タイプが Location, Country のいずれかであるオブジェクトを返します。 |
例
- inR 関数を使用して、オブジェクト タイプが "Computers" でインバウンド参照タイプが "A reference" または "IP Address" のすべてのオブジェクトを返す AQL クエリは、次のとおりです。
connectedTickets() 関数の使用
connectedTickets() 関数は、チケットが接続されているオブジェクトのフィルタリングに使用されます。適切な Jira クエリ言語 (JQL) クエリを指定することで、特定の Jira 課題を選択できます。JQL クエリが未指定な場合は、Jira 課題が接続されているすべてのオブジェクトが返されます。
| 名前 | 説明 |
|---|---|
| connectedTickets() | チケットが接続されているすべてのオブジェクトが返されます。 |
| connectedTickets(JQL query) | 指定の JQL クエリに一致するチケットが接続されているオブジェクトが返されます。 |
例
- このクエリは JQL クエリ (labels IS empty) を接続されているすべての課題で実行して、その結果に基づいてオブジェクトを返します。
objectTypeAndChildren() 関数を使用する
この関数は、特定のオブジェクト タイプのオブジェクト (およびその子) を返すために使用されます。
| 名前 | 説明 |
|---|---|
| objectTypeAndChildren(Name) | Name とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。名前にスペースが含まれている場合は、必ず二重引用符で囲んでください。 |
| objectTypeAndChildren(ID) | ID とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。 |
例
- "Hardware" オブジェクト タイプからのすべてのオブジェクトと子オブジェクトを返す AQL クエリは、次のとおりです。
関数、参照、AQL は、さまざまな優れた方法で組み合わせられます。たとえば、あるオブジェクトに添付されている 1 つのカスタム フィールドに複数のオブジェクト参照を追加して、これらの参照を次のような特定のキーで検索できます。
object HAVING inboundReferences(Key IN (${MyCustomField${0}}))または、ドット表記を使用して次のような特定のラベルで検索できます。
object HAVING inboundReferences(Label IN (${Portfolios.label${0}}))上記の 2 つのクエリでは、アセット プレースホルダーが使用されることにご注意ください。
発注
任意の 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」句で指定された属性が含まれていない場合、返されるオブジェクトの順序は任意になります。
- 属性名の代わりにプレースホルダー ラベルを使用して、設定されたラベルでオブジェクトを並べ替えられます。
例
- これらの検索結果はキーの降順に並びます。
