アセット クエリ言語 (AQL) 構文を使用する
アセット クエリ言語 (AQL) は、アセットで 1 つ以上のオブジェクトを対象とした検索クエリを作成するための言語形式です。AQL を使用すると、任意のオブジェクトまたはオブジェクト グループを検索で返したり、オブジェクトのフィルタリングまたは変更、カスタム フィールドの作成、プロセスの自動化などを行ったりできます。
AQL は、[AQL による詳細検索] またはオブジェクトのカスタム フィールド内で使用できます。これは、アセットの最も強力で動的な機能の 1 つです。
基本的な構文
AQL クエリの基本的な構文は <attribute> <operator> <value/function> です。オブジェクトの属性が指定された演算子および値と一致すると、クエリによって 1 つ以上のオブジェクトが返されます。
例: Owner = "Ted Anderson"
この AQL クエリでは、所有者が Ted Anderson であるすべてのオブジェクトが返されます。値にスペースが含まれているため、"Ted Anderson" のように引用符で囲まれています。
特殊文字の構文
AQL には定義された構文があり、正確に入力する必要があります。
AQL では、大文字と小文字が区別されません。
値または属性にスペースが含まれている式を使用する場合は、上記の "Ted Anderson" の例のように、値を囲む引用符を含める必要があります。
値または属性に引用符が含まれている式を使用する場合は、引用符の前にバックスラッシュを置いてエスケープする必要があります。たとえば「15" Screen」のような名前のオブジェクトがある場合は、検索時に「
15\” Screen」と入力します。AQL で指定する属性名は、アセット スキーマに存在する必要があります。そうでない場合、AQL は無効とみなされます。
AQL には所定の構文があり、正確に入力する必要があります。主なガイドラインは次のとおりです。
AQL では、大文字と小文字は区別されません。
値または属性にスペースが含まれている場合は、引用符で値を囲みます。たとえば、
"Ted Anderson"のようにします。値または属性に引用符が含まれている場合は、バックスラッシュで引用符をエスケープします。たとえば、15" Screen のようなオブジェクト名の場合、
15\” Screenのようにします。AQL で指定する属性名は、アセット スキーマに存在する必要があります。そうでなければ、AQL は無効になります。
AQL は次のタスクを実行する際に役立ちます。
ドット表記
AQL のドット表記は、オブジェクトの参照チェーンを横断するために使用されます。<attribute>.<attribute> <operator> <value/function> という形式を使用すると、親オブジェクトが参照するオブジェクトに基づいて情報が返されます。
例: “Belongs to Department”.Name = HR
ここで、Employee オブジェクト タイプには "Belongs to Department" という参照属性が含まれています。このクエリでは、人事部門に属するすべての従業員が返されます。
参照属性にはスペースが含まれているため、正しい形式で認識されるように二重引用符で囲まれています。
キーワード
AQL では、キーワードを使用して、特定の属性ではなくプロパティに基づいてオブジェクトが返されるようにすることができます。構文は <keyword> <operator> <value/function> のようになります。
たとえば、特定のオブジェクト タイプのすべてのオブジェクトが返されるようにするには、objectType キーワードを使用できます。
例: objectType = “Employee”
次の表は、サポートされているキーワードと例を示しています。
キーワード | 説明 |
|---|---|
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"ユーザー ロールでは、オブジェクト タイプ ID やスキーマ ID にはアクセスできません。これらの値を管理者またはマネージャーにリクエストすることで、クエリを実行できます。
また、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 タイプのすべてのオブジェクトを返します。 |
not like | クエリの入力のサブセットと一致する値を除外します。 | objecttype=Employees and Office not like Stock 'Stock' という文字を含まない Office 属性値のある Employees タイプのすべてのオブジェクトを返します。 |
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 クエリを作成できます。次に例を示します。
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 つの引数を渡します。1 つは AQL クエリで、もう 1 つはオプションの参照タイプ引数です。
AQL 引数: 実行するクエリです。他の参照関数を含めることもできます。
参照タイプ引数: クエリを特定の参照タイプに限定するためにオプションで使用します。
シリアル番号 | 名前 | 説明 |
|---|---|---|
a |
| インバウンド参照のあるオブジェクトをフィルタリングします。この参照オブジェクトは、関数への引数として提供された AQL クエリに一致するものです。 (例: object having inboundReferences() のような AQL クエリは、関数に対する空の AQL 引数がすべてのインバウンド参照オブジェクトと一致するため、インバウンド参照のあるすべてのオブジェクトを返します。 ただし、object having inboundReferences(Name="John") のようなクエリの例では、属性 Name があり Name の値が「John」のようなインバウンド参照オブジェクトのあるすべてのオブジェクトを返します。 |
B |
| これは、(a) で説明されている inboundReferences(AQL) 関数から派生したものです。 これを使用すると、参照タイプを 1 つ以上の値として指定することによって、インバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。 参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [追加値 (Additional Value)] フィールドです。 (例: 「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 のいずれかであるオブジェクトを返します。 |
connectedTickets() 関数の使用
AQL の connectedTickets() 関数を使用すると、Jira 作業項目が接続されているオブジェクトをフィルタリングできます。JQL クエリを指定して、検索の対象とする特定の Jira 作業をフィルタリングします。JQL クエリを指定しない場合は、Jira 作業項目が接続されているすべてのオブジェクトが返されます。
該当する AQL 関数に対する引数として、JQL を指定する必要があります (例: object having connectedTickets(Project = VK))。
connectedTickets() 関数は Confluence のアセット マクロでは動作しません。Confluence でのアセット データの表示の詳細については、こちらをご確認ください。
名前 | 説明 |
|---|---|
connectedTickets(JQL query) | 指定の JQL クエリに一致するチケットが接続されているオブジェクトが返されます。 たとえば、クエリ: object HAVING connectedTickets(labels is empty) は JQL クエリ (labels is empty) を接続されているすべてのチケットで実行して、その結果に基づいてオブジェクトを返します。 |
objectTypeAndChildren() 関数を使用する
AQL の 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 つのクエリでは、アセット プレースホルダーが使用されます。アセット プレースホルダーの詳細については、こちらをご確認ください。
この強力な関数を使用すると、特に否定などの演算を伴う複雑なクエリを処理する場合に、すぐには明らかにならない結果を得ることができます。結果を正確に解釈するには、クエリプロセスを次の 2 段階のアクションと考えると役立ちます。
JQL の実行: 最初のステップでは、JQL を使用して関連する Jira 作業項目をフィルタリングします。
AQL の実行: 次のステップでは、JQL クエリによって返された結果に AQL ロジックを適用し、フィルタリングされた作業項目セットを操作します。
これらのステップに分解することで、特に複雑な条件や否定条件を扱う場合に、クエリ結果をより適確に理解して絞り込むことができます。
既定では、アセット オブジェクトの詳細ビューに未解決の関連チケットが表示されます。
発注
次の構文を追加することで、AQL クエリの結果を並べ替えることができます。
pgsqlCopyEditorder by [AttributeName|label] [asc|desc]
order by 節を指定しなければ、既定の順序はオブジェクト タイプの
label属性による昇順になります。order by 句の属性が参照タイプである場合は、ドット表記を使用して参照オブジェクトの属性で並べ替えることができます。
たとえば、
Employeeオブジェクトの参照Departmentで並べ替えるには、order by Employee.Departmentのようにします。深さは無制限ですが、ドットが増えるたびにクエリのパフォーマンスに影響します。
昇順 (
asc) を使用すると、欠損値がリストの一番上に表示されます。order by 節で使用する属性は、アセット スキーマに存在している必要があります。そうでなければ、AQL は無効になります。
labelプレースホルダーを使用して、設定されているラベルでオブジェクトを並べ替えることができます。複数の属性による順序づけはサポートされていません。
order by 句で指定した属性が結果に見つからない場合、順序は任意になります。
この内容はお役に立ちましたか?