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

Insight クエリ言語 (IQL) を使用する

IQL (Insight クエリ言語) は、Insight で 1 つ以上のオブジェクトの検索クエリを作成するための言語形式です。IQL を使用すると、Insight で任意のオブジェクトまたはオブジェクトのグループを検索で返したり、オブジェクトのフィルタリング、オブジェクトの変更、カスタム フィールドの作成、自動化などを行ったりできます。

これは Insight のもっとも強力でダイナミックな機能の 1 つです。


基本的な構文

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

例: オーナー = “Ted Anderson”

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

特殊文字の構文

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

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

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

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

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

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


ドット表記

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

例: “Belongs to Department”.”Name”= HR

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

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


キーワード

IQL でキーワードを使用すると、オブジェクトの属性ではなくオブジェクトのプロパティに基づく 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".

このキーワードを使用すると、検索結果に遅延が生じる場合があります。Insight のインストール サイズが大きくなるほど、このキーワードを使用したクエリの実行にかかる時間が長くなります。

オブジェクト

オブジェクトの検索は次のように制限できます。"object having inboundReferences()" では、インバウンド参照を持つすべてのオブジェクトを検索します。

objectId

次のように、オブジェクト ID でオブジェクトを検索できます。"objectId = 114".オブジェクト ID はオブジェクトのキーにある番号ですが、プレフィックスがありません。たとえば、オブジェクトのキーが ITSM-1111 の場合、プレフィックスは ITSM でありオブジェクト IDは 1111 です。スキーマ間でオブジェクトを移動すると、キーが変更されることがあることにご注意ください。 

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

1 objectType = "Host"

Insight ユーザー ロールの場合は、オブジェクト タイプ ID とスキーマ ID が表示されないことに注意してください。Insight 管理者または Insight マネージャーからこれらの値を取得して、それを使用して IQL クエリを実行できます。

objectId ではなく、任意のオブジェクト タイプで Key 属性を使用すると特定のオブジェクトを検索できます。

例: Key="ITSM-1111" は、キーが ITSM-1111 である一意のオブジェクトを返します


演算子

演算子を使用すると、より詳細な論理式を作成できます。

次の表は、IQL でサポートされている演算子を示します。

演算子

説明

IQL クエリの例

=

大文字と小文字を区別しない値の等価テスト。

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 などの演算子を使用すると、さらに大規模で複雑な IQL 式を作成できます。

AND 演算子でリンクされた 2 つのステートメントを含む IQL クエリ:

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

関数 

複数の関数を使用して、IQL 式に動的な値を指定できます。

タイプ

関数名

説明

日時

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

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

例: objecttype = Computer and User = currentUser()

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

currentReporter()

IQL クエリでこの関数を呼び出すと、カスタム フィールドの現在の報告者に接続されているユーザー属性をフィルタリングできます。クエリでフィルタリングに使用する属性は、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()")


参照関数

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

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

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

シリアル番号

名前

説明

a

  • inboundReferences(IQL)

  • inR(IQL)

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

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

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

B

  • inboundReferences(IQL, referenceTypes)

  • inR(IQL, refTypes)

これは、(a) で説明されている inboundReferences(IQL) 関数から派生したものです

これを使用すると、参照タイプを 1 つ以上の値として指定することによって、インバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。

参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [追加値 (Additional Value)] フィールドです。

例: object having inR(objectType = "File System", refType IN ("Depends")) のような IQL クエリは

「File System」というインバウンド参照オブジェクトがあり、その File System オブジェクトの参照タイプが 「Depends」であるオブジェクトを返します。

同様に、object having inR(objectType = "File System", refType IN ("Depends", "Installed", "Using")) のようなクエリは

File System というインバウンド参照オブジェクトがあり、その File System オブジェクトの参照タイプが Depends、Installed、Using のいずれかであるオブジェクトを返します。

c

  • outboundReferences(IQL)

  • outR(IQL)

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

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

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

d

  • outboundReferences(IQL, referenceTypes)

  • outR(IQL, refTypes)

これは、(b) で説明されている outboundReferences(IQL) 関数から派生したものです。

これを使用すると、参照タイプを 1 つ以上の値として指定することによって、アウトバウンド参照オブジェクトをさらにフィルタリングできます。これは "IN" 演算子を使用して行えます。

参照タイプは、オブジェクト タイプの参照オブジェクトを定義するときに属性に指定する [追加値 (Additional Value)] フィールドです。

例: object having outR(objectType = "Employees", refType IN ("Location")) のような IQL クエリは

アウトバウンド参照オブジェクト Employees があり、その Employees オブジェクトの参照タイプが "Location" であるオブジェクトを返します。

同様に、object having outR(objectType = "Employees", refType IN ("Location", "Country")) のような IQL クエリは

アウトバウンド参照オブジェクト Employees があり、その Employees オブジェクトの参照タイプが Location, Country のいずれかであるオブジェクトを返します。

connectedTickets() 関数の使用

connectedTickets() 関数は、チケットが接続されているオブジェクトのフィルタリングに使用されます。適切な Jira クエリ言語 (JQL) クエリを指定することによって、特定の Jira 課題を選択できます。JQL クエリが指定されていない場合は、Jira 課題が接続されているすべてのオブジェクトが返されます。その IQL 関数への引数として、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 とその子によって指定されたオブジェクト タイプに基づき、オブジェクトをフィルタリングします。

「Asset Details」オブジェクト タイプからのすべてのオブジェクトと子オブジェクトを返す IQL クエリは、次のとおりです。

1 objectType in objectTypeAndChildren("Asset Details")

参照、関数、IQL を組み合わせる

関数、参照、IQL は、さまざまな優れた方法で組み合わせられます。たとえば、あるオブジェクトに添付されている 1 つのカスタム フィールドに複数のオブジェクト参照を追加して、これらの参照を次のような特定のキー:

object HAVING inboundReferences(Key IN (${MyCustomField${0}}))

または、ドット表記を使用して次のような特定のラベルで検索できます。

object HAVING inboundReferences(Label IN (${Portfolios.label${0}}))

上記の 2 つのクエリでは、Insight プレースホルダーが使用されることに注意してください。これについては、次の詳細をお読みください。 Here.

これらの関数は、正式な名前 (inboundReferencs) を使用するか略称 (inR) として書き出せます。その動作は同じです。

この強力な関数を使用すると、特に否定を使用するなど複雑なクエリが構築された場合に、一見明らかではない結果が生成される可能性があることにご注意ください。これを解釈するには、クエリを 2 つのステップ アクションとして考える必要があります。

  1. JQL 実行

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

混乱を避けるため、Insight オブジェクト詳細ビューには、Unresolved 接続チケットがデフォルトで表示されることに注意してください。


発注

任意の IQL に次のサフィックスを追加すると、クエリの結果を並び替えられます。

order by [AttributeName|label] [asc|desc]

  • order by 句を指定しない場合、デフォルトはオブジェクト タイプの labe 属性によって昇順になります。

  • order by 句で指定された属性がオブジェクト参照タイプである場合は、ドット表記を使用して参照オブジェクトの属性で並べ替えられます。任意の Employee オブジェクトの参照 Department オブジェクトで並べ替える場合は、order by Employee.Department のように句を記述できます。この操作の深度は無制限です。ただし、order by 句のすべてのドットは、その特定の IQL のパフォーマンス低下の原因になることに注意してください。 

  • 見つからない値はリストの上部に表示されます。これは、クエリ内の順序が昇順である場合に true になります: "asc"。

  • IQL で指定された属性名は、Insight に存在する必要があります。そうでない場合、IQL は無効とみなされます。属性の名前を入力するときは、大文字または小文字のどちらでも使用できます。

  • 結果に「order by」句で指定された属性が含まれていない場合、返されるオブジェクトの順序は任意になります。 

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

これらの検索結果は、キーの降順に並べられます。

最終更新日 2021年07月11日)
次でキャッシュ 8:59 AM on Oct 20, 2021 |

その他のヘルプ