Partager via

Utilisation de l’API de recherche dans le modèle de complément SharePoint

  • Article

L’approche que vous utilisez pour exécuter des recherches avec le service de recherche SharePoint est différente dans le nouveau modèle de complément SharePoint et dans le code de confiance totale. Dans un scénario standard de code de confiance totale (FTC) / solution de batterie de serveurs, le modèle objet côté serveur SharePoint (remplacements du composant WebPart Content By Query) ou les services web de recherche ont été utilisés pour exécuter des recherches avec le service de recherche SharePoint.

Dans un scénario de modèle de complément SharePoint, vous exécutez des recherches avec le service de recherche SharePoint via les API CSOM ou REST.

Conseils importants

En règle générale, nous aimerions fournir les instructions générales suivantes pour créer et configurer des collections de sites et des sous-sites, puis y déployer des artefacts, des configurations et des ressources de personnalisation.

  • L’utilisation de l’authentification AppOnly n’est pas prise en charge pour les opérations du service de recherche.
    • Cela est dû au fait que le service de recherche accède au service de profil utilisateur pour rechercher des informations de profil utilisateur et que l’UPS ne prend pas en charge l’authentification AppOnly.
    • Par conséquent, étant donné que la pertinence de la recherche et d’autres facettes de recherche dépendent d’un utilisateur donné et de ses attributs de profil, le modèle d’authentification AppOnly ne fonctionnera pas.

Options permettant d’exécuter des recherches avec le service de recherche SharePoint

Vous disposez d’un ensemble d’options pour exécuter des recherches avec le service de recherche SharePoint.

  • API CSOM .NET
  • JavaScript CSOM (JSOM) API
  • API REST

API CSOM .NET

Dans cette option, vous utilisez l’API CSOM .Net pour exécuter des recherches avec le service de recherche SharePoint.

  • Cette API est disponible uniquement dans le code .Net managé.

Quand est-elle adaptée ?

  • Cette API convient parfaitement aux compléments hébergés par le fournisseur, aux opérations de longue durée ou à d’autres scénarios côté serveur qui s’exécutent sur la plateforme .Net.
  • Voici quelques exemples de ces scénarios : ASP.NET sites web MVC, services API Web ASP.NET, console .Net ou applications Windows, et Azure Web Jobs.

Mise en route

L’exemple suivant montre comment exécuter des recherches avec le service de recherche SharePoint avec l’API CSOM .Net. Cet exemple montre également comment accéder au profil d’un utilisateur pour personnaliser les résultats de la recherche.

Api de recherche et page de personnalisation. Texte dans l’image : effectuer une recherche dans l’API De recherche. Fournir un filtre de recherche pour la requête de recherche à l’échelle du locataire : la zone de texte contient le mot Test. Texte du bouton : Effectuer une recherche simple. Effectuez une recherche personnalisée de tous les modèles de site à l’aide des données de profil. Si À propos de moi ne contient PAS de texte AppTest, nous recherchons uniquement les sites qui sont des sites d’équipe (WebTemplate = STS). Si AppTest est présent, nous effectuons une recherche sur tous les sites. Scénario : afficher des sites ou des données agrégées à partir d’emplacements spécifiques en fonction du profil utilisateur. L’exemple serait d’agréger des pages d’actualités qui sont étiquetées uniquement avec l’identificateur correspondant à l’emplacement ou à la ville de l’utilisateur actuel. Texte du bouton : effectuer une recherche personnalisée.

L’article Guide pratique pour effectuer des requêtes de recherche personnalisées avec CSOM (vidéo PnP O365) vous guide dans Search.PersonalizedResults (exemple PnP O365).

La méthode btnPerformSearch_Click dans la classe Default.aspx.cs exécute une recherche pour la valeur de texte que l’utilisateur entre dans la zone de recherche et étend la recherche à tout le contenu stocké dans une collection de sites. Le paramètre contentclass:"STS_Site » limite l’étendue de recherche aux collections de sites.

protected void btnPerformSearch_Click(object sender, EventArgs e)
{
    var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);

    using (var clientContext = spContext.CreateUserClientContextForSPHost())
    {
        // Since in this case we want only site collections, let's filter based on result type
        string query = searchtext.Text + " contentclass:\"STS_Site\"";
        ClientResult<ResultTableCollection> results = ProcessQuery(clientContext, query);
        lblStatus1.Text = FormatResults(results);
    }
}

La méthode btnPersonalizedSearch_Click dans la classe Default.aspx.cs exécute la même recherche que la méthode btnPerformSearch_Click et ajoute également un paramètre supplémentaire basé sur le profil de l’utilisateur actuel. La classe PeopleManager est utilisée pour accéder aux propriétés de profil de l’utilisateur actuel.

protected void btnPersonalizedSearch_Click(object sender, EventArgs e)
{
    var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);

    using (var clientContext = spContext.CreateUserClientContextForSPHost())
    {
        // Load user profile properties
        PeopleManager peopleManager = new PeopleManager(clientContext);
        PersonProperties personProperties = peopleManager.GetMyProperties();
        clientContext.Load(personProperties);
        clientContext.ExecuteQuery();
        // Check teh value for About Me to investigate current values
        string aboutMeValue = personProperties.UserProfileProperties["AboutMe"];
        string templateFilter = ResolveAdditionalFilter(aboutMeValue);
        // Let's build the query
        string query = "contentclass:\"STS_Site\" " + templateFilter;
        ClientResult<ResultTableCollection> results = ProcessQuery(clientContext, query);
        lblStatus2.Text = FormatResults(results);
    }
}

La méthode ResolveAdditionalFilter de la classe Default.aspx.cs évalue les propriétés de profil de l’utilisateur actuel et retourne un paramètre de recherche applicable. Dans cet exemple, si la propriété de profil utilisateur aboutMeValue contient AppTest, le paramètre de recherche WebTemplate=STS est retourné. Ce paramètre limite l’étendue de recherche aux sites créés avec le modèle STS (Site d’équipe).

private string ResolveAdditionalFilter(string aboutMeValue)
{
    if (!aboutMeValue.Contains("AppTest"))
    {
        return "WebTemplate=STS";
    }

    return "";
}

Dans les deux cas, la méthode ProcessQuery de la classe Default.aspx.cs utilise la classe SearchExecutor pour exécuter la requête de recherche et retourner les résultats.

private ClientResult<ResultTableCollection> ProcessQuery(ClientContext ctx, string keywordQueryValue)
{
    KeywordQuery keywordQuery = new KeywordQuery(ctx);
    keywordQuery.QueryText = keywordQueryValue;
    keywordQuery.RowLimit = 500;
    keywordQuery.StartRow = 0;
    keywordQuery.SelectProperties.Add("Title");
    keywordQuery.SelectProperties.Add("SPSiteUrl");
    keywordQuery.SelectProperties.Add("Description");
    keywordQuery.SelectProperties.Add("WebTemplate");
    keywordQuery.SortList.Add("SPSiteUrl", Microsoft.SharePoint.Client.Search.Query.SortDirection.Ascending);
    SearchExecutor searchExec = new SearchExecutor(ctx);
    ClientResult<ResultTableCollection> results = searchExec.ExecuteQuery(keywordQuery);
    ctx.ExecuteQuery();
    return results;
}

JavaScript CSOM (JSOM) API

Dans cette option, vous utilisez l’API JavaScript CSOM (JSOM) pour exécuter des recherches avec le service de recherche SharePoint.

  • Cette API est disponible uniquement dans le code JavaScript côté client.

Quand est-elle adaptée ?

  • Cette API convient parfaitement aux compléments hébergés par SharePoint et aux compléments hébergés par un fournisseur s’exécutant sur n’importe quelle plateforme web.
  • Voici quelques exemples de ces scénarios : ASP.NET sites web MVC, sites web PHP, sites web Python, etc.

Prise en main

L’exemple de code suivant montre comment exécuter des recherches avec le service de recherche SharePoint avec l’API JavaScript CSOM (JSOM). Cet exemple exécute une recherche pour tous les éléments qui contiennent le terme « Blizzard ».

var context = SP.ClientContext.get_current();

var keywordQuery =
new Microsoft.SharePoint.Client.Search.Query.KeywordQuery(context);

keywordQuery.set_queryText("Blizzard");

var searchExecutor =
new Microsoft.SharePoint.Client.Search.Query.SearchExecutor(context);

results = searchExecutor.executeQuery(keywordQuery);

context.executeQueryAsync(onGetEventsSuccess, onGetEventsFail);

API REST

Dans cette option, vous utilisez l’API REST pour exécuter des recherches avec le service de recherche SharePoint.

  • Cette API est la plus flexible, car elle est disponible à la fois dans le code côté serveur et côté client.
  • Le point de terminaison racine de l’API REST du service de recherche SharePoint est :
    • <https:// tenant>/site/_api/search/query
  • Voici quelques exemples simples :

    • Recherche par mot clé

      https://tenant/site/_api/search/query?querytext='{Apples}'

    • Sélection de propriétés spécifiques

      https://tenant/site/_api/search/query?querytext='test'&selectproperties='Rank, Title'

    • Tri

      https://tenant/site/_api/search/query?querytext='Oranges'&sortlist='LastModifiedTime:ascending'

Quand est-elle adaptée ?

Cette API convient parfaitement aux compléments hébergés par SharePoint et aux compléments hébergés par un fournisseur s’exécutant sur n’importe quelle plateforme web.

  • Voici quelques exemples de ces scénarios : ASP.NET sites web MVC, sites web PHP, sites web Python, services API Web ASP.NET, console .Net ou applications Windows, Azure Web Jobs, etc.

Prise en main

Option côté serveur

L’exemple suivant montre comment exécuter des recherches avec le service de recherche SharePoint avec l’API REST à partir de code .Net managé.

  • EmployeeDirectory (Contenu de formation OfficeDev)

    La méthode Index dans la classe HomeController.cs exécute une recherche pour tous les utilisateurs dont le nom commence par la valeur de texte sur laquelle l’utilisateur clique.

    var spContext = SharePointContextProvider.Current.GetSharePointContext(HttpContext);

string accessToken = spContext.UserAccessTokenForSPHost;

//Build the REST API request
StringBuilder requestUri = new StringBuilder()
.Append(spContext.SPHostUrl)
.Append("/_api/search/query?querytext='LastName:")
.Append(startLetter)
.Append("*'&selectproperties='LastName,FirstName,WorkEmail,WorkPhone'&sourceid='B09A7990-05EA-4AF9-81EF-EDFAB16C4E31'&sortlist='FirstName:ascending'");

//Create HTTP Client
HttpClient client = new HttpClient();
//Add the REST API request
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, requestUri.ToString());
//Set accept header
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/xml"));
//Set Bearer header equal to access token
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

//Send the REST API request
HttpResponseMessage response = await client.SendAsync(request);
//Set the response
string responseString = await response.Content.ReadAsStringAsync();

Le Guide pratique pour créer des compléments SharePoint qui tirent parti de la recherche (vidéo PnP O365) vous guide tout au long du répertoire EmployeeDirectory (contenu de formation OfficeDev).

Option côté client

L’exemple de code suivant montre comment exécuter des recherches avec le service de recherche SharePoint avec l’API REST à partir de JavaScript. Cet exemple exécute une recherche pour tous les éléments qui contiennent le terme « Crosse ».

$.ajax({
    url: "http://site/_api/search/" +
          "query?querytext='{Lacrosse}‘",
    method: "GET",
    headers: {
        "accept": "application/json;odata=verbose",
    },
    success: onSuccess,
    error: onError
});

Exemples PnP

S’applique à

  • Office 365 multi-locataire (MT).
  • Office 365 dédiés (D)
  • SharePoint 2013 en local