searchEntity: query

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

指定した検索クエリを実行します。 検索結果は応答に表示されます。

注意

Microsoft Search API の要求および応答で使用されたリソースの名前が変更されたか、削除された、または廃止されています。 廃止についての詳細は、 「詳細情報」でご確認ください。 検索 API クエリは、以前のいずれかのアプリで適宜更新します。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類 最小特権アクセス許可 より高い特権のアクセス許可
委任 (職場または学校のアカウント) Mail.Read Acronym.Read.All、Bookmark.Read.All、Calendars.Read、Chat。Read、ExternalItem.Read.All、Files。Read.All、QnA.Read.All、Sites.Read.All
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション Files.Read.All Sites.Read.All

HTTP 要求

POST /search/query

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。
Content-type application/json. 必須です。

要求本文

要求本文で、次のパラメーターを含む JSON オブジェクトを指定します。

パラメーター 型 説明
要求 searchRequest コレクション それぞれが JSON BLOB で書式設定された 1 つ以上の検索要求のコレクション。 各 JSON BLOB には、応答で予期されるリソースの種類、基になるソース、ページング パラメーター、要求されたフィールド、および実際の検索クエリが含まれています。 エンティティ型の特定の組み合わせの検索、検索結果の並べ替えまたは集計に関する 既知の制限 事項に注意してください。

応答

成功した場合、このメソッドは HTTP 200 OK 応答コードと、応答本文の searchResponse オブジェクトのコレクションを返します。

結果リソースに秘密度ラベルがある場合、各 searchHit オブジェクトに sensitivityLabel プロパティを含めることができます。

例

例 1: 検索要求を実行するための基本的な呼び出し

次の例は、検索を実行して予想されるコネクタ アイテムを取得する方法を示しています。

要求

POST https://graph.microsoft.com/beta/search/query
Content-type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "externalItem"
      ],
      "contentSources": [
        "/external/connections/connectionfriendlyname"
      ],
      "region": "US",
      "query": {
        "queryString": "contoso product"
      },
      "from": 0,
      "size": 25,
      "fields": [
        "title",
        "description"
      ]
    }
  ]
}

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "searchTerms": [
        "searchTerms-value"
      ],
      "hitsContainers": [
        {
          "hits": [
            {
              "hitId": "1",
              "rank": 1,
              "summary": "_summary-value",
              "resource": "The source field will contain the underlying graph entity part of the response"
            }
          ],
          "total": 47,
          "moreResultsAvailable": true
        }
      ]
    }
  ]
}

例 2: queryTemplate を使用するための基本的な呼び出し

次の例は、クエリ可能プロパティ createdBy を使用して、ユーザーが作成したすべてのファイルを取得する方法を示しています。

要求

POST https://graph.microsoft.com/beta/search/query
Content-type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "listItem"
      ],
      "region": "US",
      "query": {
        "queryString": "contoso",
        "queryTemplate":"{searchTerms} CreatedBy:Bob"
      },
      "from": 0,
      "size": 25
    }
  ]
}

応答

次の例は応答を示しています。

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "searchTerms": [
                "contoso"
            ],
            "hitsContainers": [
                {
                    "hits": [
                        {
                            "hitId": "1",
                            "rank": 1,
                            "summary": "_summary-value",
                            "resource": {
                                "@odata.type": "#microsoft.graph.listItem",
                                "id": "c23c7035-73d6-4bad-8901-9e2930d4be8e",
                                "createdBy": {
                                    "user": {
                                        "displayName": "Bob",
                                        "email": "[email protected]"
                                    }
                                },
                                "createdDateTime": "2021-11-19T17:04:18Z",
                                "lastModifiedDateTime": "2023-03-09T18:52:26Z"
                            },
                            "sensitivityLabel": {
                                "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e288",
                                "displayName": "Confidential",
                                "tooltip": "Data intended only for approved recipients.",
                                "priority": 4,
                                "color": "#FF8C00"
                            }
                        }
                    ],
                    "total": 1,
                    "moreResultsAvailable": false
                }
            ]
        }
    ]
}