• 製品
  • 使用を開始する
  • 関連ドキュメント
  • リソース

AQL (アセット クエリ言語) を使用する

アセット クエリ言語 (AQL) は、1 つ以上のオブジェクトの検索クエリを作成するために Jira Service Managementアセットで使用される言語形式です。AQL によって、検索にあるアセットでオブジェクトまたはオブジェクトのグループを返して、オブジェクトの絞り込みや変更、カスタム フィールドの作成、自動化などを行えます。

これは、アセットのもっとも強力で動的な機能の 1 つです。


基本的な構文

AQL クエリの基本的な構文は <attribute> <operator> <value/function> です。これらのオブジェクトの属性が指定の演算子および値と一致すると、クエリによって 1 つ以上のオブジェクトが返されます。 

例: オーナー = “Ted Anderson”

この基本的な AQL クエリは、Owner が "Ted Anderson" であるすべてのオブジェクトを返します。値の名前にスペースがあるため、"Ted Anderson" は引用符で囲まれます。

特殊文字の構文

AQL には定義された構文があり、正確に入力する必要があります。

  • AQL では、大文字と小文字が区別されます (属性の名前を除く)。

  • 値または属性にスペースが含まれている式を使用する場合は、上記の "Ted Anderson" の例のように、値を囲む引用符を含める必要があります。

  • 値または属性に引用符が含まれている式を使用する場合は、引用符をバックスラッシュで囲んでエスケープする必要があります。たとえば「15" Screen」のような名前のオブジェクトがある場合は、検索時に「15\”\ Screen」と入力します。

  • AQL で指定する属性名は、アセット スキーマに存在する必要があります。そうでない場合、AQL は無効とみなされます。属性の名前を入力する際は、大文字と小文字のどちらでも使用できます。

AQL は次のタスクを実行する際に役立ちます。


ドット表記

ドット表記は、オブジェクトの参照チェーンを下に移動するために AQL で使用されます。フォーマット <attribute>.<attribute> <operator> <value/function> は、親オブジェクトで参照されるオブジェクトに基づく情報を返します。

例: “Belongs to Department”.Name = HR

この場合、Employeee オブジェクト タイプには「Belongs to Department」という参照属性があります。このクエリは、人事部門に属するすべての従業員を返します。

参照される属性にはスペースが含まれているため、二重引用符で囲まれています。


キーワード

AQL でキーワードを使用すると、オブジェクトの属性ではなくオブジェクトのプロパティに基づく 1 つ以上のオブジェクトを返せます。その構文は <keyword> <operator> <value/function> のようになります。

たとえば、objectType キーワードを使用して特定のオブジェクト タイプのすべてのオブジェクトを、anyAttribute キーワードを使用して特定の属性を持つタイプのすべてのオブジェクトを返せます。次の表では、サポートされているキーワードとその例について説明します。

キーワード

説明

objectSchema

検索結果を次のように特定のオブジェクト スキーマ名に制限できます。objectSchema = "ITSM Schema".

objectSchemaId

検索結果はオブジェクト スキーマ ID に制限できます。例:objectSchemaId in (1, 2).

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 です。

"Host" オブジェクト タイプを持つすべてのオブジェクトを返す AQL クエリは次のとおりです。

1 objectType = "Host"

注: アセット ユーザー ロールの場合、オブジェクト タイプとスキーマの各 ID は表示されません。アセット管理者またはアセット マネージャーからこれらの値を取得して使用し、AQL クエリを実行できます。

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

Price2000 ドル未満かどうかを確認します。

>

指定の値より大きいかどうかのテスト

Price > 2000

Price2000 ドルを超えているかどうかを確認します。

<=

指定の値以下かどうかのテスト

Price <= 2000

Price2000 ドル以下かどうかを確認します。

>=

指定の値以上かどうかのテスト

Price >= 2000

Price が 2000 ドル以上かどうかを確認します。

いいね!

クエリ内の入力のサブセットと値を照合します。大文字と小文字は区別されません。

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")

StockholmOslo、または San Jose のいずれかの値を持つ Office タイプのすべてのオブジェクトを返します。

not in()

指定された引数との一致が見つかった結果を除外します。

Office not in (Stockholm, Oslo, "San Jose")

StockholmOslo、または San Jose のいずれかの値を持たない Office タイプのすべてのオブジェクトを返します。

startswith

値が指定された入力で始まる一致を検索します。大文字と小文字は区別されません。

Office startsWith St

文字 "St" または "ST" で始まる Office タイプの値と一致する結果を返します。

〜で終わる

値が指定された入力で終わる一致を検索します。大文字と小文字は区別されません。

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 つのステートメントが含まれています。

1 objectType = "Host" AND "Operating System" = "Ubuntu (64-bit"

関数 

複数の関数によって、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 範囲でのフィルター

例:
"IP Address" IN CIDR("192.0.0.0/8")
"IP Address" IN CIDR("192.168.0.0/16")

ユーザー

 

currentUser()

AQL クエリでこの関数を呼び出すと、現在の (ログイン) ユーザーに接続されているユーザー属性をフィルタリングできます。クエリでフィルタリングに使用する属性は、User タイプである必要があります。

例: objecttype = Computer and User = currentUser()

この関数は、CurrentUser が選択されている、つまりユーザーがログインしているときに機能します。

currentReporter()

AQL クエリでこの関数を呼び出すと、カスタム フィールドの現在の報告者に接続されているユーザー属性をフィルタリングできます。 クエリでフィルタリングに使用する属性は、User タイプである必要があります。

例: User = currentReporter()

この関数は、課題が選択されている場合にのみ機能して、現在の課題に表示される報告者を参照します。

user(user1, user2, ..)

関数の引数リストで指定したユーザーへの参照を持つオブジェクトをフィルタリングできます。フィルタリングに使用する属性は、User タイプである必要があります。 

この関数は、フィルタリングする User タイプ属性が複数の値を許可する場合、つまりこのカーディナリティが複数の場合のみ、複数の引数で機能します。

例: オブジェクト タイプ Team には属性 Member があります。この属性は User タイプです。さらに、この属性のカーディナリティは 3 と設定されています。ユーザー adminmanager がメンバーである一連の 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()")


参照関数

参照関数は、AQL や参照型引数の 2 つの引数を取る関数です。基本的に、参照関数によって、特定の参照タイプを持つオブジェクトのサブセットに対して AQL クエリを実行できます。このようなクエリはオブジェクト合計数が小さいサブセットで実行することで、結果や処理時間を制限できます。

  • AQL 引数には、参照関数を持つ AQL を含む任意の AQL を指定できます。 

  • 参照型引数はオプションです。

シリアル番号

名前

説明

a

  • inboundReferences(AQL)

  • inR(AQL)

インバウンド参照のあるオブジェクトをフィルタリングします。この参照オブジェクトは、関数への引数として提供された AQL クエリに一致するものです。

例:object having inboundReferences() のような AQL クエリは、関数に対する空の AQL 引数がすべてのインバウンド参照オブジェクトと一致するため、インバウンド参照のあるすべてのオブジェクトを返します。

ただし、object having inboundReferences(Name="John") のようなクエリの例では、属性 Name があり Name の値が「John」のようなインバウンド参照オブジェクトのあるすべてのオブジェクトを返します。

B

  • inboundReferences(AQL, referenceTypes)

  • inR(AQL, refTypes)

これは、(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

  • outboundReferences(AQL)

  • outR(AQL)

アウトバウンド参照のあるオブジェクトをフィルタリングします。この参照オブジェクトは、関数への引数として提供された AQL クエリに一致するものです。

例:object having outboundReferences() のような AQL クエリは関数への空の AQL 引数がすべてのアウトバウンド参照オブジェクトと一致するため、アウトバウンド参照のあるすべてのオブジェクトを返します。

ただし、bject having outboundReferences(Name="John") のようなクエリの例では、属性 Name があり、Name の値が "John" のようなアウトバウンド参照オブジェクトのあるすべてのオブジェクトを返します。

d

  • outboundReferences(AQL, referenceTypes)

  • outR(AQL, refTypes)

これは、(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() 関数の使用

connectedTickets() 関数は、チケットが接続されているオブジェクトのフィルタリングに使用されます。適切な Jira クエリ言語 (JQL) クエリを指定することで、特定の Jira 課題を選択できます。JQL クエリが指定されていない場合は、Jira 課題が接続されているすべてのオブジェクトが返されます。その AQL 関数への引数として、JQL を指定する必要があります (例:object having connectedTickets(Project = VK))。

名前

説明

connectedTickets(JQL query)

指定の JQL クエリに一致するチケットが接続されているオブジェクトが返されます。

たとえば、クエリ: object HAVING connectedTickets(labels is empty)

は JQL クエリ (labels is empty) を接続されているすべてのチケットで実行して、その結果に基づいてオブジェクトを返します。

objectTypeAndChildren() 関数を使用する

この関数は、特定のオブジェクト タイプのオブジェクト (およびその子) を返すために使用されます。

名前

説明

objectTypeAndChildren(Name)

Name とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。名前にスペースが含まれている場合は、必ず二重引用符で囲んでください。

objectTypeAndChildren(ID)

ID とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。

この AQL クエリは "Asset Details" オブジェクト タイプからのすべてのオブジェクトと子オブジェクトを返します。

1 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 つのステップ アクションとして考える必要があります。

  1. JQL 実行

  2. JQL 結果で動作する AQL 実行

アセット オブジェクト詳細ビューには、初期設定で未解決の接続チケットが表示されます。


発注

任意の 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」句で指定された属性が含まれていない場合、返されるオブジェクトの順序は任意になります。 

  • 属性名の代わりにプレースホルダー ラベルを使用して、設定されたラベルでオブジェクトを並べ替えられます。 

  • 複数の属性による順序づけはサポートされていません。

 

その他のヘルプ