Such-API-Verwendung im SharePoint-Add-In-Modell

Artikel
04/08/2023

Der Ansatz, den Sie zum Ausführen von Suchvorgängen mit dem SharePoint-Suchdienst verwenden, unterscheidet sich im neuen SharePoint-Add-In-Modell von dem bei voll vertrauenswürdigem Code. In einem typischen FTC-Szenario (Full Trust Code) / Farm Solution wurden das serverseitige SharePoint-Objektmodell (Content By Query-Webpart-Außerkraftsetzungen) oder die Suchwebdienste verwendet, um Suchvorgänge mit dem SharePoint-Suchdienst auszuführen.

In einem SharePoint-Add-In-Modellszenario führen Sie Suchvorgänge mit dem SharePoint-Suchdienst über die CSOM- oder REST-APIs aus.

Allgemeine Richtlinien

Als Faustregel möchten wir die folgenden allgemeinen Richtlinien bereitstellen, um Websitesammlungen und Unterwebsites zu erstellen und zu konfigurieren und dann Artefakte, Konfigurationen und Brandingressourcen für diese bereitzustellen.

Die Verwendung der AppOnly-Authentifizierung wird für Suchdienstvorgänge nicht unterstützt.
- Dies liegt daran, dass der Suchdienst auf den Benutzerprofildienst zugreift, um Benutzerprofilinformationen zu durchsuchen, und das UPS keine AppOnly-Authentifizierung unterstützt.
- Da die Relevanz der Suche und andere Suchfacets von einem bestimmten Benutzer und dessen Profilattributen abhängen, funktioniert das AppOnly-Authentifizierungsmuster daher nicht.

Optionen zum Ausführen von Suchvorgängen mit dem SharePoint-Suchdienst

Sie haben eine Reihe von Optionen zum Ausführen von Suchvorgängen mit dem SharePoint-Suchdienst.

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

.NET CSOM-API

In dieser Option verwenden Sie die .NET CSOM-API, um Suchvorgänge mit dem SharePoint-Suchdienst auszuführen.

Diese API ist nur in verwaltetem .NET-Code verfügbar.

Wann ist die Option geeignet?

Diese API eignet sich hervorragend für vom Anbieter gehostete Add-Ins, zeitintensive Vorgänge oder andere serverseitige Szenarien, die auf der .NET-Plattform ausgeführt werden.
Beispiele für diese Szenarien sind ASP.NET MVC-Websites, ASP.NET-Web-API-Dienste, .NET-Konsole oder Windows-Anwendungen und Azure-Webaufträge.

Erste Schritte

Im folgenden Beispiel wird veranschaulicht, wie Suchvorgänge mit dem SharePoint-Suchdienst mit der .NET-CSOM-API ausgeführt werden. In diesem Beispiel wird auch veranschaulicht, wie Sie auf das Profil eines Benutzers zugreifen, um die Suchergebnisse zu personalisieren.

Search.PersonalizedResults (O365 PnP-Beispiel)

Das Thema Ausführen personalisierter Suchabfragen mit CSOM (O365 PnP Video) führt Sie durch die Search.PersonalizedResults (O365 PnP-Beispiel).

Die btnPerformSearch_Click-Methode in der Default.aspx.cs-Klasse führt eine Suche nach dem Textwert aus, den der Benutzer in das Suchfeld eingibt, und bezieht den Suchbereich auf alle Inhalte, die in einer Websitesammlung gespeichert sind. Der Parameter contentclass:"STS_Site" beschränkt den Suchbereich auf Websitesammlungen.

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);
    }
}

Die btnPersonalizedSearch_Click-Methode in der Default.aspx.cs-Klasse führt dieselbe Suche wie die btnPerformSearch_Click-Methode aus und fügt außerdem einen zusätzlichen Parameter hinzu, der auf dem Profil des aktuellen Benutzers basiert. Die PeopleManager-Klasse wird verwendet, um auf die Profileigenschaften des aktuellen Benutzers zuzugreifen.

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);
    }
}

Die ResolveAdditionalFilter-Methode in der Default.aspx.cs-Klasse wertet die Profileigenschaften des aktuellen Benutzers aus und gibt einen anwendbaren Suchparameter zurück. Wenn in diesem Beispiel die aboutMeValue-Benutzerprofileigenschaft AppTest enthält, wird der Suchparameter WebTemplate=STS zurückgegeben. Dieser Parameter beschränkt den Suchbereich auf Websites, die mit der STS-Vorlage (Teamwebsite) erstellt wurden.

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

    return "";
}

In beiden Fällen verwendet die ProcessQuery-Methode in der Default.aspx.cs-Klasse die SearchExecutor-Klasse, um die Suchabfrage auszuführen und die Ergebnisse zurückzugeben.

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

In dieser Option verwenden Sie die JavaScript-CSOM-API (JSOM), um Suchvorgänge mit dem SharePoint-Suchdienst auszuführen.

Diese API ist nur in clientseitigem JavaScript-Code verfügbar.

Wann ist die Option geeignet?

Diese API eignet sich hervorragend für von SharePoint gehostete Add-Ins und vom Anbieter gehostete Add-Ins, die auf einer beliebigen Webplattform ausgeführt werden.
Einige Beispiele für diese Szenarien sind ASP.NET MVC-Websites, PHP-Websites, Python-Websites usw.

Erste Schritte

Im folgenden Codebeispiel wird veranschaulicht, wie Suchvorgänge mit dem SharePoint-Suchdienst mit der JavaScript CSOM(JSOM)-API ausgeführt werden. In diesem Beispiel wird eine Suche nach allen Elementen ausgeführt, die den Begriff "Schneesturm" enthalten.

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);

REST-API

In dieser Option verwenden Sie die REST-API, um Suchvorgänge mit dem SharePoint-Suchdienst auszuführen.

Diese API ist die flexibelste, da sie sowohl im serverseitigen als auch im clientseitigen Code verfügbar ist.
Der Rest-API-Stammendpunkt des SharePoint-Suchdiensts lautet:
- <https:// mandant>/site/_api/search/query

Hier sind einige einfache Beispiele:

Stichwortsuche

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

Auswählen bestimmter Eigenschaften

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

Die Sortierung

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

Wann ist die Option geeignet?

Diese API eignet sich hervorragend für von SharePoint gehostete Add-Ins und vom Anbieter gehostete Add-Ins, die auf einer beliebigen Webplattform ausgeführt werden.

Beispiele für diese Szenarien sind ASP.NET MVC-Websites, PHP-Websites, Python-Websites, ASP.NET-Web-API-Dienste, .NET-Konsole oder Windows-Anwendungen, Azure-Webaufträge usw.

Erste Schritte

Serverseitige Option

Im folgenden Beispiel wird veranschaulicht, wie Suchvorgänge mit dem SharePoint-Suchdienst mit der REST-API aus verwaltetem .NET-Code ausgeführt werden.

EmployeeDirectory (OfficeDev-Schulungsinhalte)

Die Index-Methode in der Klasse HomeController.cs führt eine Suche nach allen Benutzern aus, deren Nachname mit dem Textwert beginnt, auf den der Benutzer klickt.

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();

Das Thema How to build SharePoint add-ins that leverage search (O365 PnP Video) führt Sie durch das EmployeeDirectory (OfficeDev Training Content).

Clientseitige Option

Im folgenden Codebeispiel wird veranschaulicht, wie Suchvorgänge mit dem SharePoint-Suchdienst mit der REST-API aus JavaScript ausgeführt werden. In diesem Beispiel wird eine Suche nach allen Elementen ausgeführt, die den Begriff "Lacrosse" enthalten.

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

Ausführen personalisierter Suchabfragen mit CSOM (O365 PnP Video)
EmployeeDirectory (OfficeDev-Schulungsinhalte)
Erstellen von SharePoint-Add-Ins, die die Suche nutzen (O365 PnP Video)
Leitfadenartikel unter https://aka.ms/OfficeDevPnPGuidance
Verweise in MSDN unter https://aka.ms/OfficeDevPnPMSDN
Videos bei https://aka.ms/OfficeDevPnPVideos

PnP-Beispiele

Search.PersonalizedResults (O365 PnP-Beispiel)
Beispiele und Inhalte bei Microsoft 365 Patterns and Practices (PnP)

Gilt für

Office 365 mit mehreren Mandanten (MT)
Office 365 dediziert (D)
SharePoint 2013 lokal

Freigeben über

Such-API-Verwendung im SharePoint-Add-In-Modell

Allgemeine Richtlinien

Optionen zum Ausführen von Suchvorgängen mit dem SharePoint-Suchdienst

.NET CSOM-API

Wann ist die Option geeignet?

Erste Schritte

JavaScript CSOM(JSOM)-API

Wann ist die Option geeignet?

Erste Schritte

REST-API

Wann ist die Option geeignet?

Erste Schritte

Serverseitige Option

Clientseitige Option

PnP-Beispiele

Gilt für

Zusätzliche Ressourcen

Freigeben über

Such-API-Verwendung im SharePoint-Add-In-Modell

Allgemeine Richtlinien

Optionen zum Ausführen von Suchvorgängen mit dem SharePoint-Suchdienst

.NET CSOM-API

Wann ist die Option geeignet?

Erste Schritte

JavaScript CSOM(JSOM)-API

Wann ist die Option geeignet?

Erste Schritte

REST-API

Wann ist die Option geeignet?

Erste Schritte

Serverseitige Option

Clientseitige Option

Verwandte Links

PnP-Beispiele

Gilt für

Zusätzliche Ressourcen