Microsoft Search
Quick Start

Configure Azure App

Register App

Go to Microsoft Azure Portal and navigate to App registrations. Register a new app with the option New registration.

App Registration
New Registration

Type the name and select the option Accounts in this organizational directory only and submit the registration with register. Omit the Redirect URI for your app.

Your App Registration

Create Client Secret

Add Client Secret under Certificates & secrets → Client secrets.

Client Secrets

Submit your new client secret with the option New client secret.

Add Client Secret

Define API Permissions

The connector requires access to the Microsoft Search External Connection/Item API for synchronizing external content items and to Users/Groups API for synchronizing principal information. To assign the required permission to your app, navigate to API permissions inside your app menu.

New Registration

With the option Add a permission, you can assign new permissions to your app.

Add Permission

Register all permissions as Microsoft Graph API Application permission.

Graph API Application Permission

Add External Connection/Item Permissions

To access the Microsoft Search API, following permissions are required by the app:

  • ExternalConnection.ReadWrite.OwnedBy

  • ExternalItem.ReadWrite.All

  • ExternalItem.ReadWrite.OwnedBy

External Connection/Item Permissions

Add Users and Groups Permissions

To access user and group information for your tenant, the app requires following permissions:

  • Group.Read.All

  • User.Read.All

User Permission
Group Permission
Make sure to grant admin consent for all permissions.

Configure External Connection

The item metadata that the connector sends to Microsoft Search is defined by a schema, this schema is generated within Microsoft Search and defines the fields used by Microsoft Search. Therefore, the schema must be generated before a connector can run a traversal to ingest documents. This section describes the steps required to create a default schema within Microsoft Search, the request to generate the schema can be modified as required prior to creating the schema. There are 3 steps to setup Microsoft Search prior to using the connector to ingest documents:

  • Authenticate against Microsoft Search

  • Create a Connection ID within Microsoft Search

  • Generate a schema within the Connection ID

These steps are performed via the Microsoft Search API, the following guide provides a Postman Workspace for calling the Microsoft Search API endpoints:

https://docs.microsoft.com/en-us/graph/connecting-external-content-connectors-api-postman

The Connection ID can only contain ASCII alphanumeric characters, and must be between 3 and 32 characters long. e.g. 2ecbffec1da74fab8057b4530d3c442a.

Get Connection

To check if a connection already exists.

GET https://graph.microsoft.com/v1.0/external/connections/{{connectionId}}

Authentication:Access Token

Create new Connection

POST https://graph.microsoft.com/v1.0/external/connections

Headers

Content-Type:application/json

Authentication:Access Token

Body Request

  {
      "name": "Raytion Microsoft Search Connector for Filesystem 1.0",
      "description": "Raytion Microsoft Search Connector for Filesystem 1.0",
      "id": "2ecbffec1da74fab8057b4530d3c442a"
  }

Create default Schema

POST https://graph.microsoft.com/v1.0/external/connections/{{connectionId}}/schema

Authentication:Access Token

Headers

  • Content-Type:application/json

  • prefer:respond-async

Body Request:

{
    "baseType": "microsoft.graph.externalItem",
    "properties": [
        {
            "name": "author",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "labels": [
                "lastModifiedBy"
            ]
        },
        {
            "name": "breadcrumbs",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "breadcrumbUrls",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "clickUrl",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "labels": [
                "url"
            ]
        },
        {
            "name": "contributors",
            "type": "stringCollection",
            "isSearchable": "true",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "contributorsRefiner",
            "type": "stringCollection",
            "isQueryable": "true",
            "isRetrievable": "true",
            "isRefinable": "true",
            "labels": [
                "authors"
            ]
        },
        {
            "name": "createdDate",
            "type": "dateTime",
            "isQueryable": "true",
            "isRetrievable": "true",
            "labels": [
                "createdDateTime"
            ],
            "isRefinable": "true"
        },
        {
            "name": "fileExtension",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "labels": [
                "fileExtension"
            ]
        },
        {
            "name": "fileName",
            "type": "string",
            "isSearchable": "true",
            "isQueryable": "true",
            "isRetrievable": "true",
            "labels": [
                "fileName"
            ]
        },
        {
            "name": "fileType",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "isRefinable": "true"
        },
        {
            "name": "iconUrl",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "false",
            "isRetrievable": "true"
        },
        {
            "name": "itemType",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "itemTypeRefiner",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "isRefinable": "true"
        },
        {
            "name": "keywords",
            "type": "string",
            "isSearchable": "true",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "keywordsRefiner",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "isRefinable": "true"
        },
        {
            "name": "labels",
            "type": "stringCollection",
            "isSearchable": "true",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "labelsRefiner",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "isRefinable": "true"
        },
        {
            "name": "languages",
            "type": "stringCollection",
            "isQueryable": "true",
            "isRetrievable": "true",
            "isRefinable": "true"
        },
        {
            "name": "lastModifiedDate",
            "type": "dateTime",
            "isQueryable": "true",
            "isRetrievable": "true",
            "labels": [
                "lastModifiedDateTime"
            ],
            "isRefinable": "true"
        },
        {
            "name": "mimeType",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "parentItemUrl",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "parentItemTitle",
            "type": "string",
            "isSearchable": "true",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "previewUrl",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "rootItemTitle",
            "type": "string",
            "isSearchable": "true",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "rootItemTitleRefiner",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "isRefinable": "true"
        },
        {
            "name": "rootItemUrl",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "sourceItemType",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "sourceName",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "sourceUrl",
            "type": "string",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "sourceNameRefiner",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true",
            "isRefinable": "true"
        },
        {
            "name": "spaceCategories",
            "type": "stringCollection",
            "isSearchable": "false",
            "isQueryable": "true",
            "isRetrievable": "true"
        },
        {
            "name": "title",
            "type": "string",
            "isSearchable": "true",
            "isQueryable": "true",
            "isRetrievable": "true",
            "labels": [
                "title"
            ]
        }
    ]
}