詳細検索: AQL - アセット クエリ言語
Let's look at some example AQL searches to find objects in the following object schema.
基本的な構文
AQL クエリの基本的な構文は、<attribute> <operator> <value/function> です。これらのオブジェクトの属性が指定の演算子と値と一致すると、クエリによって 1 つ以上のオブジェクトが返されます。
例
A basic AQL query that returns all objects for which the Contact is "Jennifer Evans". Note the quotations around "Jennifer Evans" — they're needed because of a space in the value name.
特殊文字の構文
AQL には定義された構文があり、正確に入力する必要があります。
- AQL では、大文字と小文字が区別されます。
- 値または属性にスペースが含まれている式を使用する場合は、「Ted Anderson」の例のように値を囲む引用符を含める必要があります。
- 値または属性に引用符が含まれている式を使用する場合は、引用符をバックスラッシュで囲んでエスケープする必要があります。たとえば、15" Screen のような名前のオブジェクトがある場合は、検索時に "15\" Screen" と入力します。
- AQL で指定する属性名は、アセット スキーマに存在する必要があります。そうでない場合、AQL は無効とみなされます。属性名では大文字と小文字が区別されます。
ドット表記
ドット表記は、オブジェクトの参照チェーンを下に移動するために AQL で使用されます。フォーマット <attribute>.<attribute> <operator> <value/function> は、親オブジェクトで参照されるオブジェクトに基づく情報を返します。
例
- In this case, the Connected Device object type has a referenced attribute called Host. The query returns all the Connected Devices which have the Host ATL_DEV02.
- Note that if the referenced attribute contains spaces, it needs to be enclosed with a pair of double quotes.
キーワード
AQL でキーワードを使用すると、オブジェクトの属性ではなくオブジェクトのプロパティに基づく 1 つ以上のオブジェクトを返せます。その構文は <keyword> <operator> <value/function> のようになります。
たとえば、objectType キーワードを使用して特定のオブジェクト タイプのすべてのオブジェクトを、anyAttribute キーワードを使用して特定の属性を持つタイプのすべてのオブジェクトを返せます。次の表では、サポートされているキーワードとその例について説明します。
| キーワード | 説明 |
|---|---|
| objectType | 検索結果は特定のオブジェクト タイプ名に制限できます (例: objectType = "Employment Start Date")。属性にはスペースが含まれているため、二重引用符で囲まれています。 |
| objectTypeId | You can limit the search result on object type ids. For example, objectTypeId in (1, 2). |
| anyAttribute | すべてのオブジェクトのすべての属性で、関連する一致を検索できます。例: "anyAttribute = 123.123.123.123" このキーワードによって検索結果に遅延が生じる場合があります。アセットのインストール サイズが大きくなるほど、このキーワードによるクエリの実行にかかる時間が長くなります。 |
| オブジェクト | You can limit the search to the object, for example, "object having inboundReferences()" will search all objects having any inbound references to it. |
| objectId | You can find an object by object Id, for example, "objectId = 114". Note that the object id is the number from the Key of the object, but without the prefix. For example, if the Key of your object is ITSM-1111, then the prefix is ITSM and the object id is 1111. Note that the Key could change when you move objects across schemas. |
例
An AQL query that returns all objects with the "Device" object type.
演算子
演算子を使用すると、より詳細な論理式を作成できます。
次の表は、AQL でサポートされている演算子を示します。
| 演算子 | 説明 | AQL クエリの例 |
|---|---|---|
| = | 大文字と小文字を区別しない値の等価テスト。 | "Office = Stockholm" Checks if the Office attribute has a value equal to Stockholm or STOCKHOLM |
| == | 大文字と小文字を区別する値の等価テスト。 | "Office==Stockholm" Checks if the Office attribute has a value equal to Stockholm considering the case of the input provided. |
| != | 不等式テスト | objecttype=Employee and Office!=Stockholm Checks if the Employee object has an attribute Office whose value is NOT equal to Stockholm. |
| < | 指定の値より小さいかどうかのテスト。 | "Price < 2000" Price が 2000 ドル未満かどうかをチェックします。 |
| > | 指定の値より大きいかどうかのテスト | "Price > 2000" Price が 2000 ドルを超えているかどうかをチェックします。 |
| <= | 指定の値以下かどうかのテスト | "Price <= 2000" Price が 2000 ドル以下かどうかを確認します。 |
| >= | 指定の値以上かどうかのテスト | "Price >= 2000" Checks if the Price is greater than or equal to 2000 dollars. |
| いいね！ | クエリ内の入力のサブセットと値を照合します。大文字と小文字は区別されません。 | "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") Returns all objects of Office type which HAVE one of these values: Stockholm, Oslo or San Jose. |
| not in() | 指定された引数との一致が見つかった結果を除外します。 | Office not in ("Stockholm", "Oslo", "San Jose") Returns all objects of Office type which DO NOT HAVE one of these values: Stockholm, Oslo or San Jose. |
| startswith | 値が指定された入力で始まる一致を検索します。大文字と小文字は区別されません。 | "Office startsWith St" Returns results which match values of Office type starting with the characters "St" or "ST" |
| endswith | 値が指定された入力で終わる一致を検索します。大文字と小文字は区別されません。 | "Office endsWith St" Returns results which match values of Office type ending with the characters "St" or "ST" |
| is | 値が存在するかどうかをテストするのに役立ちます。 | "Office is EMPTY" Checks whether the value of the Office type exists and returns results accordingly. "Office is not EMPTY" Checks whether the value of the Office type is not empty. |
| dot operator(.) | オブジェクトの Referenced タイプ属性にナビゲートできます。 この演算子は一般に、次の場合に使用されます。 inboundReferences() または inR() 関数。 outboundReferences() または outR() 関数。 order by 句。 | "Country.Office = Stockholm" The dot operator here navigates to the referenced object Office in the attribute Country and compares Office with the value Stockholm. |
| having | inboundReferences() または outboundReferences() 関数で使用 | "object having inboundReferences()" インバウンド参照を持つすべてのオブジェクトを返します。 |
| not having | inboundReferences() または outboundReferences() 関数で使用 | "object not having inboundReferences()" インバウンド参照を持つすべてのオブジェクトを除外して、結果を返します。 |
例
An AQL query that uses the IN operator and objectType to return objects of three different object types.
組み合わせ演算子
AND/OR などの演算子を使用すると、さらに大規模で複雑な AQL 式を作成できます。
例
An AQL query that includes two statements linked with the AND operator.
関数
複数の関数を使用して、AQL 式に動的な値を指定できます。
| タイプ | 関数名 | 説明 |
|---|---|---|
| 日付 | now() startOfDay() endOfDay() startOfWeek() endOfWeek() startOfMonth() endOfMonth() startOfYear() endOfYear() | 幅広い関数を使用して、日時を含むクエリを記述できます。 m は分、h は時間、d は日数、w は週数をそれぞれ表します。 For example, a query with a condition like: Created > "now(-2h 15m)" returns all objects created in the last 2 hours and 15 minutes. For example, a query containing something like: objectType = Employees and "Employment End Date" < endOfMonth(-90d) returns all Employee objects whose Employment End Date falls before 90 days from the current month's end date. You may also check for an upcoming date, for example, check when the license of a software expires by the end of the year. Your query can then include something like : licenseEndDate = endOfYear() 他のすべての日付関数も同様の方法で使用できます。 |
| IP アドレス | CIDR(IP RANGE) | CIDR(IP RANGE) - Filter on IP ranges For example |
| ユーザー | currentUser() | AQL クエリでこの関数を呼び出すと、現在の (ログイン) ユーザーに接続されているユーザー属性をフィルタリングできます。クエリでフィルタリングに使用する属性は、User タイプである必要があります。 For example, objecttype = Computer and User = currentUser() この関数は、CurrentUser が選択されている、つまりユーザーがログインしているときに機能します。 |
currentReporter() | AQL クエリでこの関数を呼び出すと、カスタム フィールドの現在の報告者に接続されているユーザー属性をフィルタリングできます。クエリでフィルタリングに使用する属性は、User タイプである必要があります。 For example, User = currentReporter() この関数は、課題が選択されている場合にのみ機能して、現在の課題に表示される報告者を参照します。 | |
user(user1, user2, ..) | 関数の引数リストで指定したユーザーへの参照を持つオブジェクトをフィルタリングできます。フィルタリングに使用する属性は、User タイプである必要があります。 This function will work with multiple arguments only if the User type attribute that you filter on allows multiple values, that is, the cardinality for it is more than one. For example, an object type Team has an attribute Member. This attribute is of User type. Additionally, this attribute has been configured to have a cardinality of 3. If you want to search a set of Team objects where the users: admin and manager are its members, you can write the following query: objecttype=Team and Member having user("admin", "manager") | |
| グループ | group(group1, group2, ...) | 特定のグループ内のユーザーに接続されている任意のオブジェクトをフィルタリングできます。フィルタリングに使用する属性は、User タイプである必要があります。 For example, User in group("jira-users", "jira-administrators") |
| user(user1, user2, ...) | 特定のグループ内のユーザーに接続されている任意のオブジェクトをフィルタリングします。フィルターに使用する属性は、Group タイプである必要があります。 For example, Group having user("currentReporter()") | |
| プロジェクト | currentProject() | 現在選択されている Jira プロジェクトに接続されているオブジェクトを絞り込みます。チケットのコンテキスト内でのみ機能します。 For example, Project = currentProject() |
参照関数
参照関数は、AQL や参照型引数の 2 つの引数を取る関数です。基本的に、参照関数を使用すると、特定の参照タイプのオブジェクトのサブセットに対して AQL クエリを実行できます。このようなクエリはオブジェクト合計数が小さいサブセットで実行することで、結果や処理時間を制限できます。
- AQL 引数には、参照関数を持つ AQL を含む任意の AQL を指定できます。
- 参照型引数はオプションです。
| シリアル番号 | 名前 | 説明 |
|---|---|---|
| a |
| インバウンド参照のあるオブジェクトをフィルタリングします。この参照は関数への引数として提供された AQL クエリに一致するものです。 For example, 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" 演算子を使用して行えます。 Reference Type is the Additional Value field that you provide on an attribute when you define a referenced object for an object type as shown in the screenshot below ("Installed" reference type).
For example, an AQL query like this: object having inR(objectType = "File System", refType IN ("Depends")) will return objects which have inbound referenced objects of "File System" and only for those File System objects whose Reference Type is "Depends". Similarly, an AQL query like: object having inR(objectType = "File System", refType IN ("Depends", "Installed", "Using")) will return objects which have inbound referenced objects of File System and for those File System objects whose Reference Type is any of these: Depends, Installed, Using |
| c |
| アウトバウンド参照のあるオブジェクトをフィルタリングします。この参照は、関数への引数として提供された AQL クエリに一致するものです。 For example, 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. But an example query like: object having outboundReferences(Name="John") will return all objects which have an outbound referenced object with an attribute Name and value for Name as "John". |
| d |
| これは、(b) で説明されている outboundReferences(AQL) 関数から派生したものです。 これを使用すると、参照タイプを 1 つ以上の値として指定することによって、アウトバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。 参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [さらなるメリット (Additional Value)] フィールドです。 For example, an AQL query like this: object having outR(objectType = "Employees", refType IN ("Location")) will return objects which have outbound referenced objects of Employees and only for those Employees objects whose Reference Type is "Location". Similarly, an AQL query like: object having outR(objectType = "Employees", refType IN ("Location", "Country")) will return objects which have outbound referenced objects of Employees and for those Employees objects whose Reference Type is any of these: Location, Country |
例
An AQL query that uses the inR function to return all objects that have inbound references.
An AQL query that uses the inR function to return all objects that are of object type "Connected Device", and have inbound references of type "Installed".
connectedTickets() 関数の使用
connectedTickets() 関数は、チケットが接続されているオブジェクトのフィルタリングに使用されます。適切な Jira クエリ言語 (JQL) クエリを指定することで、特定の Jira 課題を選択できます。JQL クエリが未指定な場合は、Jira 課題が接続されているすべてのオブジェクトが返されます。
| 名前 | 説明 |
|---|---|
| connectedTickets() | チケットが接続されているすべてのオブジェクトが返されます。 |
| connectedTickets(JQL query) | 指定の JQL クエリに一致するチケットが接続されているオブジェクトが返されます。 |
例
This query runs a JQL query (labels IS empty) on all connected issues, and then returns objects based on the results.
objectTypeAndChildren() 関数を使用する
この関数は、特定のオブジェクト タイプのオブジェクト (およびその子) を返すために使用されます。
| 名前 | 説明 |
|---|---|
| objectTypeAndChildren(Name) | Name とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。名前にスペースが含まれている場合は、必ず二重引用符で囲んでください。 |
| objectTypeAndChildren(ID) | ID とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。 |
例
An AQL query that returns all objects and child objects from the "Host" object type.
関数、参照、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]考慮事項
- If you do not specify an order by clause, the default will be ascending order by the label attribute of an object type.
- If the attribute specified in the order by clause is of the object reference type you can use dot notation to order by attributes on the referenced object. For example, if you want to order by the referenced Department object of an Employee object, you can mention the clause in this way: order by Employee.Department. This can be done in unlimited depth. However, note that the every dot in the order by clause will decrease the performance of that particular AQL.
- 見つからない値はリストの上部に表示されます。これは、クエリ内の順序が昇順である場合に true になります: "asc"。
- AQL で指定された属性名は、アセットに存在する必要があります。そうでない場合、AQL は無効とみなされます。属性名では大文字と小文字が区別されます。
- If the results do not contain the attribute specified in the "order by" clause, the order of the objects returned will be arbitrary.
- 属性名の代わりにプレースホルダー ラベルを使用して、設定されたラベルでオブジェクトを並べ替えられます。
例
これらの検索結果は、キーの降順に並べられます。
