リソースの検索およびフィルタ リング

検索は、クライアントが API から情報を取得することを可能にする機能です。結果は、通常、複数の多様なリソースを含むドキュメントです。
apmdevops102jp
検索
は、クライアントが API から情報を取得することを可能にする機能です。結果は、通常、複数の多様なリソースを含むドキュメントです。
検索では、GET 要求(検索文字列を「q」HTTP クエリ パラメータの値として渡す)または POST 要求(検索文字列を要求本文とともに送信する)を受け入れる明示的なリソース(/search)が使用されます。応答には、JSON ドキュメントと _embedded リソースの形式の結果が含まれます。
フィルタ リング
は、特定のリソースのフィルタされたコレクションを返す API の機能です。
フィルタリングは、フィルタ リングをサポートする各リソースの一部として実装されます。フィルタ リングをサポートするリソースは、HAL のテンプレート化されたリンクでフィルタリング機能を通知します(以下の例の「q」パラメータに注意してください)。
{
    "_links": {
        "self": {
            "href": "/agent{?q,page,projection,size,sort}",
            "templated": true
         }
    }
...
...
}
クライアントは、GET 要求(検索文字列を「q」HTTP クエリ パラメータの値として渡す)または POST 要求(検索文字列を要求本文とともに送信する)によって、リソースのフィルタリング機能を使用できます。
例:
https://localhost:8443/apm/acc/agent?q=agentName:Tomcat
注:
検索リソースを常に API で使用できるわけではありません。また、フィルタ リング機能が実装されていない場合もあります。ユーザは、個々の API のマニュアルを参照して、それらの機能が利用可能かどうかを確認する必要があります。
検索およびフィルタリングでは、Lucene 構文がサポートされます。以下のパラグラフでは、CA APM の RESTful API がサポートできるクエリ文字列構文について説明します。
クエリには、1 つの語または句を二重引用符で囲んで含めることができます。ブール演算子を使用して複数の語を組み合わせることによって、より複雑なクエリを作成することができます。
フィールド
検索を実行する際は、フィールドを指定できます。フィールド名、コロン、検索する語の順で入力することにより、任意のフィールドを検索できます。複数の語による句の場合は、引用符を使用します。フィールドが指定されていない場合は、すべてのフィールドが検索されます。
例:
以下のクエリでは、Apache Tomcat という名前のすべてのエージェントが検索されます。
https://localhost:8443/apm/acc/agent?q=agentName:"Apache Tomcat"
ワイルドカード検索
検索では、1 つの語内(フレーズ クエリ内ではなく)での 1 文字および複数文字ワイルドカード検索がサポートされます。
  • 1 文字ワイルドカード検索を実行するには、「?」記号を使用します。
  • 複数文字ワイルドカード検索を実行するには、「*」記号を使用します。
例:
以下のクエリでは、名前に「Linux」が含まれるサーバ上で実行されているすべてのエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=serverName:*Linux*
正規表現検索
検索では、スラッシュ(/)間のパターンに一致する正規表現検索がサポートされます。構文はリリース間で異なる場合がありますが、現在サポートされている構文は RegExp クラスに記載されています。
例:
以下のクエリでは、指定された文字が名前に含まれているレポートが検出されます。「ACCServerWin01|Tomcat|Tomcat Agent」と「ACCServerLinux01|Tomcat|Bobcat Agent」の両方の文字列が、このクエリに適合します。
https://localhost:8443/apm/acc/diagnosticReport?q=/ACCServer.*01\|Tomcat\|.*Agent/
範囲検索
範囲クエリでは、その範囲クエリによって指定される下限と上限の間のフィールド値を持つドキュメントを検出できます。範囲クエリでは、上限および下限を含めることも除外することもできます。上限および下限を含めた範囲クエリの場合は角かっこで示し、それらを除外する範囲クエリの場合は波かっこで示します。ソートは、辞書方式で実行されます。
具体的な日付に加えて、週(w)、日数(d)、時間(h)、分(m)、秒(s)などの期間も使用できます。
例:
以下のクエリでは、2015 年 4 月 1 日(この日を含む)から現在の間に含まれる最終アクセス タイムスタンプを持つすべてのエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=lastContact:[2015-04-01 TO NOW]
以下のクエリでは、2015 年4 月 1 日から 6 月 1 日の間(ただし、4 月 1日と 6 月 1 日は除外)に含まれる最終アクセス タイムスタンプを持つすべてのエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=lastContact:{2015-04-01 TO 2015-06-01}
以下のクエリでは、直近の 5 日間に含まれる最終アクセス タイムスタンプを持つエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=lastContact:[-5d TO NOW]
以下のクエリでは、直近の 5 週間に含まれ、かつ現在より 2 日間以上古い最終アクセス タイムスタンプを持つエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=lastContact:[-5w TO -2d]
語の加重
検索構文では、検索語に基づいて検出されるドキュメントの関連性レベルを指定できます。語を加重するには、検索語の後ろにキャレット(^)記号と加重係数(数値)を追加します。加重係数が大きいほど、その語との関連性が高くなります。
ブール演算子
ブール演算子を使用することで、論理演算子によって語を組み合わせることができます。
  • または
    OR 演算子は、デフォルトの結合演算子です。これは、2 つの語の間にブール演算子がない場合に OR 演算子が使用されることを意味します。OR 演算子は、2 つの語を結び付け、いずれかの語が含まれているドキュメントを適合ドキュメントとして検出します。「OR」の代わりに「||」記号を使用することができます。
  • および
    AND 演算子を使用すると、1 つのドキュメントのテキスト内のどこかに両方の語が存在するドキュメントが検出されます。「AND」の代わりに「&&」記号を使用することができます。
  • +
    「+」(必須演算子)は、「+」記号の後の語が 1 つのドキュメントのフィールド内のどこかに存在することを要求します。
  • NOT
    NOT 演算子を使用すると、NOT の後の語が含まれるドキュメントが除外されます。「NOT」の代わりに「!」記号を使用することができます。
  • -
    「-」(禁止演算子)を使用すると、「-」記号の後の語が含まれるドキュメントが除外されます。
例:
以下のクエリでは、名前が Tomcat でログ レベルが debug に設定されているエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=agentName:Tomcat AND logLevel:debug
以下のクエリでは、Linux サーバ上で実行されているすべてのアクティブなエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=osName:Linux NOT status:away
以下のクエリでは、「Linux」を必ず含み、「server」を含む場合のあるリソースが検出されます。
https://localhost:8443/apm/acc/agent?q=+Linux server
グループ化
構文では、丸かっこによる句のグループ化(サブ クエリの形成)がサポートされています。これは、クエリのブール演算子の機能を制御するために役立つ場合があります。
例:
以下のクエリでは、名前が Tomcat で、アプリケーション サーバ バージョン 5.4 または 5.5 上で実行されているエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=(appServerVersion:5.5* OR appServerVersion:5.4*) AND agentName:Tomcat
フィールドのグループ化
構文では、丸かっこによる複数の句の単一フィールドへのグループ化がサポートされています。
例:
以下のクエリでは、Windows または Linux サーバ上で実行されているエージェントが検出されます。
https://localhost:8443/apm/acc/agent?q=osName:(Windows OR Linux)
特殊文字のエスケープ
構文では、特殊文字(+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /)のエスケープがサポートされます。
これらの文字をエスケープするには、文字の前にバック スラッシュ(\)を使用します。