searchEntity: query

  • [アーティクル]

名前空間: microsoft.graph

重要

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

指定した検索クエリを実行します。 Search結果は応答で提供されます。

注意

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 オブジェクトのコレクションを返します。

例

例 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": "Bob@contoso.com"
                                    }
                                },
                                "createdDateTime": "2021-11-19T17:04:18Z",
                                "lastModifiedDateTime": "2023-03-09T18:52:26Z"
                            }
                        }
                    ],
                    "total": 1,
                    "moreResultsAvailable": false
                }
            ]
        }
    ]
}

関連コンテンツ