クエリ

このセクションでは、フィールドの値をフィルタリングしてクエリを実行する方法について説明します。コレクションのGET操作中に、クエリに一致するエンティティのみがALM Octane REST APIによって返されます。

クロスフィルタリングの詳細については、クロスフィルターを参照してください。

クエリステートメント

フィルタリングするには、少なくとも1つのクエリフレーズで構成されるクエリステートメントを使用します。

クエリステートメントは、GETメソッドの最後に追加されます。

例: GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/{entity}?query="query statement"

  • クエリステートメントは二重引用符で囲まれています。 "query statement"

  • クエリステートメントの構文は次のとおりです。

    " <query phrase>[[<logical operator><query phrase>]] "

    つまり、クエリステートメントに複数のクエリフレーズが含まれている場合は、各クエリフレーズをAnd (;) またはOr (||) 論理演算子で区切ります。

    注: フィールドメタデータをフィルタリングする場合、特定の制限があります。たとえば、Or (||) 論理演算子はサポートされていません。詳細については、URIを使用したフィールドメタデータのフィルタリングを参照してください。

クエリフレーズ

  • クエリステートメントのクエリフレーズの構文は次のとおりです。

    ( [negate keyword] ( "<field name> <comparison operator> <value>" ) )

    注: クエリフレーズの構文の開き括弧と閉じ括弧に注意してください。

  • クエリフレーズは括弧で囲むことができます。

演算子

データ型別のサポートされている演算子

クエリで提供される値は、フィールドで宣言されたデータ型と一致している必要があります。

データ型

EQ

LT

GT

LE

GE

IN

BTW

Integer

Boolean

DateTime

String

Memo

Reference

トップに戻る

演算子の使用

演算子タイプ

演算子

機能

例
比較演算子 比較演算子は、フィールド名とその値を分離します。
 

EQ

に等しい

id EQ 1001
 

LT

より小さい

id LT 1001
 

GT

より大きい

id GT 1001
 

LE

以下

id LE 1001
 

GE

以上

id GE 1001
 

IN

値のリストにコンマで区切られて存在します。

値リスト内の項目間の関係はOR関係です。これは、値の1つが一致する限り、操作が成功することを意味します。

値のリストには、次のものも含めることができます。

  • 現在のユーザー ( [current_user] )。これは、RESTAPIを呼び出している現在ログインしているユーザーです。

  • 現在のリリース ( [current_release] )。これは、ALM Octane設定領域で標準設定値として設定されているリリースです。

id IN [current_user], 1001, 1002, 1003
 

BTW

3つのドット (...) で区切られた2つの数値で指定され、3つのドットの前にスペースがある値の範囲に存在します。これは包括的範囲です。これは、ある数以上で別の数以下と言うのと同じです。

id BTW 12 ...16 ( )
論理演算子 論理演算子は、クエリ句またはクエリステートメントを区別するために使用されます。
 

;

AND

  
 

||

OR

  
  ！

NOT

否定演算子！はオプションです。この演算子は、後続のオペランドの意味を逆にします。

  

トップに戻る

演算子の優先順位を理解する

括弧は他のすべての演算子の中で最も優先順位が高く、条件が評価される順序を制御します。

括弧で囲まれた式はネストできます。

演算子

ランク (低い数字=高いランク)

 例

()

1

次のステートメントは同等です。 

  • "(!name EQ ^test^);flag EQ true"

  • "!name EQ ^test^;flag EQ true"

!

2
; 3
|| 4

トップに戻る

値

タイプ 説明 例

Numeric

Numericは、比較演算子の後に配置されます。

/<some_entities>?query=”<some_numeric_field_name> GE 35”

id GT 1

Boolean

有効な値:trueまたはfalse。

/<some_entities>？query="<some_boolean_field_name> EQ true"

 has_attachments EQ true
String / Memo

キャレットで包む必要があります: ^ string ^

文字列内の特殊文字のエスケープがサポートされています。特殊文字のエスケープを参照してください。

文字列に一重引用符、二重引用符、または曲折アクセント記号が含まれている場合は、円記号でエスケープします。たとえば、d'Artagnanを'd\'Artagnan 'として渡します。n ^ mをn\^ mとして渡します。4つの「スコア」と7年を4つの「スコア」と7年として渡します。

ワイルドカードがサポートされています。ワイルドカードの使用を参照してください。

リテラルはトリミングされません。たとえば、文字列リテラル^ A ^を送信すると、サーバーは「A」と一致しない3文字の長さの値を取得します。

フィーチャー:  

name EQ ^Using cart^

フェーズ:

logical_name EQ ^phase.test*^
String-based フィルタリングする場合、DateTime値は文字列のように動作します。DateTimeを参照してください。  
Reference

参照値でのフィルタリングとは、参照されるエンティティのフィールド値でフィルタリングする機能を意味します。

参照値の構文は次のとおりです。

{<query phrase>[[<logical operator><query phrase>]]}

参照フィールドは、単一のエンティティまたは複数のエンティティ、つまり複数参照フィールドを参照できます。複数参照フィールドの場合、等式演算子は包含演算子として機能します。

不具合エンティティには、detected_in_releaseと呼ばれるリリースエンティティへの参照フィールドがあります。release1という名前のリリースで検出されたすべての不具合をフィルタリングします。

/defects?query=”detected_in_release EQ {name EQ ^release1^}”

detected_in_releaseフィールドのリリースを参照していないすべての不具合をフィルタリングします。

/defects?query=”detected_in_release EQ {null}”

(nullは中括弧で囲まれていることに注意してください。)
"No Value"

フィールドに値がないことを指定します。nullとして表されます。これは、ユーザーが (PUTを介して) 既存の値から文字列フィールドを無効にするたびに、クライアントはnullまたは空の文字列 ( "") を送信でき、サーバーはDB nullに格納することを意味します。これは、空の文字列が非有効な値であることを意味します。 -null許容フィールド。

"No Value" は、ブール値と文字列値を除くすべての値に関連します。文字列に "No Value" を指定する方法については、以下を参照してください。

たびに (不具合がまだ閉じられていないので、不具合の決算日が定義されていない場合には、例えば) 値が存在しない、特別なキーワードヌルが定義されるべきです。このnullキーワードは、"No Value" の概念を指定するためのフィルタリングでも使用できます。

サーバー側からの文字列 /メモフィールド値の唯一の操作は、出力サニタイズ機能のためにのみ発生する可能性があります。

REST APIは、文字列/メモフィールドをトリミングしません。

空の文字列は、NULL不可能なフィールドの有効な値ではありません。null許容文字列フィールドの場合、nullは空の文字列と一致しません。
  
DateTime

キャレットで包む必要があります: ^ datetime ^

予想される日付と時刻の形式はISO-8601です。

  • 日付には完全な日付と時刻の情報が含まれている必要があります。つまり、「日付のみ」はサポートされていません。

  • 予想される形式は次のとおりです。

    • 2018-06-10T10:13:15Z

    • 2018-03-12T16:42:11%2B01:00 (エンコードされた2018-03-12T16:42:11 + 01:00

    • 2018-03-12T16:42:11-01:00

  • 日付と時刻はUTCです。

  • 作成、更新、フィルタリングの目的で、APIコンシューマーはUTCおよびISO-8601形式を使用する必要があります。

/<some_entities>？query =”<some_date_field_name> LT ^ 2015-02-25T16:42:11Z ^

フィルタリングする場合、DateTime値は文字列のように動作します。

  

トップに戻る

特殊文字のエスケープ

文字列値での特殊文字のエスケープがサポートされています (検索する文字列に次の文字のいずれかが含まれていて、その文字でフィルタリングする場合)。

文字

エスケープ文字 (URIエンコード)

コメント

"

\" ( %5C%22 )

 

^

\^ ( %5C%5E )

 

\

\\ ( %5C%5C )

 

'

\q ( %5Cq )

 

<

\l ( %5Cl )

 

>

\g ( %5Cg )

 

*

N/A

この文字によるフィルタリングはサポートされていません

{

\{ ( %5C%7B )

 

(

\( ( %5C( )

 

)

\) ( %5C) )

 

[

\[ ( %5Cb )

 

?

\? ( %5C%3F )

 

トップに戻る

ワイルドカードの使用

サポートされているワイルドカードは*アスタリスクです。すべての文字がアスタリスクに一致します。

その文字列をフィルタリングするには... ワイルドカードを指定してください... 一致...
endingで終わる *ending the_ending ; theending; ending
startingで始まる starting* starting_here ; startinghere, starting

例: 最初の例は、文字列の存在の直接一致を示しています。2番目の例は、testで始まる値を返します。

  • /<some_entities>?query="<some_string_field_name> EQ ^existence^"

  • /<some_entities>?query="<some_string_field_name> EQ ^test*^"

トップに戻る

例

特定のユーザーによって検出されたすべての不具合をフィルタリングします

GET .../defects?query="detected_by EQ {[current_user]}"

GET .../defects?query="detected_by={ id IN 1001,1002,1003}"

GET .../defects?query="detected_by={ id BTW 1001...1003}"

GET .../defects?query="detected_by={ id IN [current_user],1001}"

ログインしたユーザーによって検出され、特定のチームの一部であるすべての不具合をフィルタリングします

GET .../defects/query="detected_by EQ {[current_user];teams EQ {id EQ 2005}}"

リリースがリリースのリストにあるすべての不具合をフィルタリングします

GET .../defects?query="release EQ {[current_release]}"

GET .../defects?query="release={id IN [current_release], 1002}"

GET .../defects?query="release={id IN 1001, 1002}"

トップに戻る

不具合は複数のユーザータグでタグ付けされます: 

{
    “type”: “defect”,
    “user_tags”: [
        {
            “id”: 1001,
            “type”: “user_tag”
        },
        {
            “id”: 2005,
            “type”: “user_tag”
        },
        {
            “id”: 3008,
            “type”: “user_tag”
        }
    ]
}

トップに戻る

次のフィルタークエリは、上記のすべての不具合を取得します。 

  • GET .../defects?query="user_tags EQ {id EQ 1001}"

  • GET .../defects?query="user_tags EQ {id EQ 1001||id EQ 2005}"

  • GET .../defects?query="user_tags EQ {id EQ 1001}||user_tags EQ {id EQ 2005}"

  • GET .../defects?query="user_tags EQ {id EQ 1001||id EQ 500000}"

  • GET .../defects?query="user_tags EQ {id EQ 1001}||user_tags EQ {id EQ 500000}"

  • GET .../defects?query="user_tags EQ {id EQ 1001;id EQ 3008}"

  • GET .../defects?query="user_tags EQ {id EQ 1001};user_tags EQ {id EQ 3008}"

  • GET .../defects?query="user_tags EQ {(id EQ 1001;id EQ 2005;id EQ 3008)||id EQ 50000000}"

  • GET .../defects?query="user_tags EQ {id EQ 1001;id EQ 2005;id EQ 3008}||user_tags EQ {id EQ 50000000}"

  • GET .../defects?query="user_tags EQ {id EQ 1001||(id EQ 2005;id EQ 50000000)}"

  • GET .../defects?query="user_tags EQ {id EQ 1001}||(user_tags EQ {id EQ 2005}; user_tags EQ {id EQ 50000000})"

  • GET .../defects?query="user_tags EQ {id EQ 1001}||user_tags EQ {null}"

トップに戻る

次のフィルタークエリは、上記のすべての不具合を取得するわけではありません。 

  • GET .../defects?query="user_tags EQ {id EQ 1001;id EQ 50000000}"

  • GET .../defects?query="user_tags EQ {id EQ 1001};user_tags EQ {id EQ 50000000}"

  • GET .../defects?query="user_tags EQ {id EQ 1001;(id EQ 5000000||id EQ 7000000)}"

  • GET .../defects?query="user_tags EQ {id EQ 1001};user_tags EQ {id EQ 5000000||id EQ 7000000}"

  • GET .../defects?query="user_tags EQ {id EQ 1001};(user_tags EQ {id EQ 5000000}|| user_tags EQ {id EQ 7000000})"

  • GET .../defects?query="user_tags EQ {id EQ 1001};user_tags EQ {null}"

トップに戻る

参照情報: