searchEntity: query

名前空間: microsoft.graph

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

この 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/v1.0/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"
      ]
    }
  ]
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Search.Query;
using Microsoft.Graph.Models;

var requestBody = new QueryPostRequestBody
{
	Requests = new List<SearchRequest>
	{
		new SearchRequest
		{
			EntityTypes = new List<EntityType?>
			{
				EntityType.ExternalItem,
			},
			ContentSources = new List<string>
			{
				"/external/connections/connectionfriendlyname",
			},
			Region = "US",
			Query = new SearchQuery
			{
				QueryString = "contoso product",
			},
			From = 0,
			Size = 25,
			Fields = new List<string>
			{
				"title",
				"description",
			},
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Search.Query.PostAsQueryPostResponseAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphsearch "github.com/microsoftgraph/msgraph-sdk-go/search"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphsearch.NewQueryPostRequestBody()


searchRequest := graphmodels.NewSearchRequest()
entityTypes := []graphmodels.EntityTypeable {
	entityType := graphmodels.EXTERNALITEM_ENTITYTYPE 
	searchRequest.SetEntityType(&entityType)
}
searchRequest.SetEntityTypes(entityTypes)
contentSources := []string {
	"/external/connections/connectionfriendlyname",
}
searchRequest.SetContentSources(contentSources)
region := "US"
searchRequest.SetRegion(&region) 
query := graphmodels.NewSearchQuery()
queryString := "contoso product"
query.SetQueryString(&queryString) 
searchRequest.SetQuery(query)
from := int32(0)
searchRequest.SetFrom(&from) 
size := int32(25)
searchRequest.SetSize(&size) 
fields := []string {
	"title",
	"description",
}
searchRequest.SetFields(fields)

requests := []graphmodels.SearchRequestable {
	searchRequest,
}
requestBody.SetRequests(requests)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
query, err := graphClient.Search().Query().PostAsQueryPostResponse(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.search.query.QueryPostRequestBody queryPostRequestBody = new com.microsoft.graph.search.query.QueryPostRequestBody();
LinkedList<SearchRequest> requests = new LinkedList<SearchRequest>();
SearchRequest searchRequest = new SearchRequest();
LinkedList<EntityType> entityTypes = new LinkedList<EntityType>();
entityTypes.add(EntityType.ExternalItem);
searchRequest.setEntityTypes(entityTypes);
LinkedList<String> contentSources = new LinkedList<String>();
contentSources.add("/external/connections/connectionfriendlyname");
searchRequest.setContentSources(contentSources);
searchRequest.setRegion("US");
SearchQuery query = new SearchQuery();
query.setQueryString("contoso product");
searchRequest.setQuery(query);
searchRequest.setFrom(0);
searchRequest.setSize(25);
LinkedList<String> fields = new LinkedList<String>();
fields.add("title");
fields.add("description");
searchRequest.setFields(fields);
requests.add(searchRequest);
queryPostRequestBody.setRequests(requests);
var result = graphClient.search().query().post(queryPostRequestBody);


const options = {
	authProvider,
};

const client = Client.init(options);

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

await client.api('/search/query')
	.post(searchResponse);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Search\Query\QueryPostRequestBody;
use Microsoft\Graph\Generated\Models\SearchRequest;
use Microsoft\Graph\Generated\Models\EntityType;
use Microsoft\Graph\Generated\Models\SearchQuery;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new QueryPostRequestBody();
$requestsSearchRequest1 = new SearchRequest();
$requestsSearchRequest1->setEntityTypes([new EntityType('externalItem'),	]);
$requestsSearchRequest1->setContentSources(['/external/connections/connectionfriendlyname', 	]);
$requestsSearchRequest1->setRegion('US');
$requestsSearchRequest1Query = new SearchQuery();
$requestsSearchRequest1Query->setQueryString('contoso product');
$requestsSearchRequest1->setQuery($requestsSearchRequest1Query);
$requestsSearchRequest1->setFrom(0);
$requestsSearchRequest1->setSize(25);
$requestsSearchRequest1->setFields(['title', 'description', 	]);
$requestsArray []= $requestsSearchRequest1;
$requestBody->setRequests($requestsArray);


$result = $graphServiceClient->search()->query()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Search

$params = @{
	requests = @(
		@{
			entityTypes = @(
			"externalItem"
		)
		contentSources = @(
		"/external/connections/connectionfriendlyname"
	)
	region = "US"
	query = @{
		queryString = "contoso product"
	}
	from = 0
	size = 25
	fields = @(
	"title"
"description"
)
}
)
}

Invoke-MgQuerySearch -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.search.query.query_post_request_body import QueryPostRequestBody
from msgraph.generated.models.search_request import SearchRequest
from msgraph.generated.models.entity_type import EntityType
from msgraph.generated.models.search_query import SearchQuery
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = QueryPostRequestBody(
	requests = [
		SearchRequest(
			entity_types = [
				EntityType.ExternalItem,
			],
			content_sources = [
				"/external/connections/connectionfriendlyname",
			],
			region = "US",
			query = SearchQuery(
				query_string = "contoso product",
			),
			from = 0,
			size = 25,
			fields = [
				"title",
				"description",
			],
		),
	],
)

result = await graph_client.search.query.post(request_body)

応答

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

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/v1.0/search/query
Content-type: application/json

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


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Search.Query;
using Microsoft.Graph.Models;

var requestBody = new QueryPostRequestBody
{
	Requests = new List<SearchRequest>
	{
		new SearchRequest
		{
			EntityTypes = new List<EntityType?>
			{
				EntityType.ListItem,
			},
			Region = "US",
			Query = new SearchQuery
			{
				QueryString = "contoso",
				QueryTemplate = "{searchTerms} CreatedBy:Bob",
			},
			From = 0,
			Size = 25,
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Search.Query.PostAsQueryPostResponseAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphsearch "github.com/microsoftgraph/msgraph-sdk-go/search"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphsearch.NewQueryPostRequestBody()


searchRequest := graphmodels.NewSearchRequest()
entityTypes := []graphmodels.EntityTypeable {
	entityType := graphmodels.LISTITEM_ENTITYTYPE 
	searchRequest.SetEntityType(&entityType)
}
searchRequest.SetEntityTypes(entityTypes)
region := "US"
searchRequest.SetRegion(&region) 
query := graphmodels.NewSearchQuery()
queryString := "contoso"
query.SetQueryString(&queryString) 
queryTemplate := "{searchTerms} CreatedBy:Bob"
query.SetQueryTemplate(&queryTemplate) 
searchRequest.SetQuery(query)
from := int32(0)
searchRequest.SetFrom(&from) 
size := int32(25)
searchRequest.SetSize(&size) 

requests := []graphmodels.SearchRequestable {
	searchRequest,
}
requestBody.SetRequests(requests)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
query, err := graphClient.Search().Query().PostAsQueryPostResponse(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.search.query.QueryPostRequestBody queryPostRequestBody = new com.microsoft.graph.search.query.QueryPostRequestBody();
LinkedList<SearchRequest> requests = new LinkedList<SearchRequest>();
SearchRequest searchRequest = new SearchRequest();
LinkedList<EntityType> entityTypes = new LinkedList<EntityType>();
entityTypes.add(EntityType.ListItem);
searchRequest.setEntityTypes(entityTypes);
searchRequest.setRegion("US");
SearchQuery query = new SearchQuery();
query.setQueryString("contoso");
query.setQueryTemplate("{searchTerms} CreatedBy:Bob");
searchRequest.setQuery(query);
searchRequest.setFrom(0);
searchRequest.setSize(25);
requests.add(searchRequest);
queryPostRequestBody.setRequests(requests);
var result = graphClient.search().query().post(queryPostRequestBody);


const options = {
	authProvider,
};

const client = Client.init(options);

const searchResponse = {
  requests: [
    {
      entityTypes: [
        'listItem'
      ],
        region: 'US',
        query: {
        queryString: 'contoso',
        queryTemplate: '{searchTerms} CreatedBy:Bob'
      },
      from: 0,
      size: 25
    }
  ]
};

await client.api('/search/query')
	.post(searchResponse);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Search\Query\QueryPostRequestBody;
use Microsoft\Graph\Generated\Models\SearchRequest;
use Microsoft\Graph\Generated\Models\EntityType;
use Microsoft\Graph\Generated\Models\SearchQuery;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new QueryPostRequestBody();
$requestsSearchRequest1 = new SearchRequest();
$requestsSearchRequest1->setEntityTypes([new EntityType('listItem'),	]);
$requestsSearchRequest1->setRegion('US');
$requestsSearchRequest1Query = new SearchQuery();
$requestsSearchRequest1Query->setQueryString('contoso');
$requestsSearchRequest1Query->setQueryTemplate('{searchTerms} CreatedBy:Bob');
$requestsSearchRequest1->setQuery($requestsSearchRequest1Query);
$requestsSearchRequest1->setFrom(0);
$requestsSearchRequest1->setSize(25);
$requestsArray []= $requestsSearchRequest1;
$requestBody->setRequests($requestsArray);


$result = $graphServiceClient->search()->query()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Search

$params = @{
	requests = @(
		@{
			entityTypes = @(
			"listItem"
		)
		region = "US"
		query = @{
			queryString = "contoso"
			queryTemplate = '{searchTerms} CreatedBy:Bob"
		}
		from = 0
		size = 25
	}
)
}

Invoke-MgQuerySearch -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.search.query.query_post_request_body import QueryPostRequestBody
from msgraph.generated.models.search_request import SearchRequest
from msgraph.generated.models.entity_type import EntityType
from msgraph.generated.models.search_query import SearchQuery
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = QueryPostRequestBody(
	requests = [
		SearchRequest(
			entity_types = [
				EntityType.ListItem,
			],
			region = "US",
			query = SearchQuery(
				query_string = "contoso",
				query_template = "{searchTerms} CreatedBy:Bob",
			),
			from = 0,
			size = 25,
		),
	],
)

result = await graph_client.search.query.post(request_body)

応答

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

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
                }
            ]
        }
    ]
}

メールメッセージを検索する
予定表のイベントを検索する
SharePoint と OneDrive (ファイル、リスト、サイト) のコンテンツを検索する
カスタム型 (Graph コネクタ) データを検索する
queryTemplate を使用した検索
検索結果を並べ替える
集計を使用して検索結果を絞り込む

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-07-25