Freigeben über

Application Lifecycle Management (ALM)-APIs

  • Artikel

ALM-APIs bieten einfache APIs für die Verwaltung der Bereitstellung Ihrer SharePoint-Framework-Lösungen und Add-Ins Ihres Mandanten. ALM-APIs unterstützen die folgenden Funktionen.

  • Hinzufügen einer SharePoint Framework-Lösung oder eines SharePoint-Add-Ins zu einem Mandanten- oder Websitesammlungs-App-Katalog.
  • Entfernen einer SharePoint Framework-Lösung oder eines SharePoint-Add-Ins aus einem Mandanten- oder Websitesammlungs-App-Katalog.
  • Aktivieren einer SharePoint Framework-Lösung oder eines SharePoint-Add-Ins, damit diese für die Installation in einem Mandanten- oder Websitesammlungs-App-Katalog verfügbar sind.
  • Deaktivieren einer SharePoint Framework-Lösung oder eines SharePoint-Add-Ins, damit diese nicht für die Installation in einem Mandanten- oder Websitesammlungs-App-Katalog verfügbar sind.
  • Installieren einer SharePoint Framework-Lösung oder eines SharePoint-Add-Ins aus einem Mandanten- oder Websitesammlungs-App-Katalog.
  • Aktualisieren einer SharePoint Framework-Lösung oder eines SharePoint-Add-Ins, wenn eine neuere Version im Mandanten- oder Websitesammlungs-App-Katalog enthalten ist.
  • Deinstallieren einer SharePoint-Framework-Lösung oder eines SharePoint-Add-Ins von einer Seite.
  • Auflisten und Abrufen aller Details zu SharePoint Framework-Lösungen oder SharePoint-Add-Ins im Mandanten- oder Websitesammlungs-App-Katalog

ALM-APIs können verwendet werden, um genau die gleichen Operationen durchzuführen, die über die Benutzeroberfläche verfügbar sind. Wenn diese APIs verwendet werden, können alle typischen Aktionen ausgeführt werden. Nachfolgend finden Sie einige der Eigenschaften für ALM-APIs:

  • Install und UnInstall von Ereignissen werden für vom Anbieter gehostete Add-Ins ausgelöst, wenn entsprechende Vorgänge auftreten.
  • ALM-APIs unterstützen nur-App-basierte Operationen nur für SharePoint-Framework-Lösungen.

ALM-APIs werden für die mandantenbezogenen Websitesammlungen und den Websitesammlung-App-Katalog unterstützt. Verwenden Sie die URL des entsprechenden App-Katalogs, um einen bestimmten App-Katalog anzusprechen. Sie müssen zuerst den App-Katalog einer Websitesammlung aktivieren, bevor Sie ihn mit den auf dieser Website dokumentierten Aktionen ansprechen können.

Wichtig

Mandantenbezogene Berechtigungen, die Mandanten-Administrationsberechtigungen erfordern, werden von den ALM-APIs nicht unterstützt.

Optionen für das Arbeiten mit ALM-APIs

ALM-APIs werden systemeigen über REST-APIs bereitgestellt, aber es gibt auch zusätzliche Clientobjektmodell (Client-Side Object Model, CSOM)-Erweiterungen, PowerShell-Cmdlets und die plattformübergreifende CLI für Microsoft 365 über SharePoint PnP-Community-Kanäle.

SharePoint-REST-API

Die ALM-APIs werden systemeigen als Endpunkte auf der SharePoint-REST-API bereitgestellt.

Der App-Katalog muss in allen HTTP-Anforderungen enthalten sein, wenn die REST-API wie in den folgenden Beispielen gezeigt verwendet wird. Ersetzen Sie den Platzhalter {app-catalog-scope} im Endpunkt mit dem Bereich des App-Katalogs. Die verfügbaren Bereichsoptionen sind tenantappcatalog und sitecollectionappcatalog.

Beispiel:

Umfang Endpunkt
Mandant https://contoso.sharepoint.com/sites/AppCatalog/_api/web/tenantappcatalog/{command}
Websitesammlung https://contoso.sharepoint.com/sites/Marketing/_api/web/sitecollectionappcatalog/{command}
  • beim Ansprechen des Mandanten-App-Katalogs, der sich auf https://contoso.sharepoint.com/sites/AppCatalog befindet, würde der Endpunkt ** sein

Hier finden Sie weitere Informationen: SharePoint-REST-API

PnP CSOM (auch bekannt als PnP-Websites-Kerne)

Das PnP CSOM implementiert die ALM-APIs über den Aufruf des SharePoint-REST-APIs.

Bevor Sie eines der ALM-APIs im PnP CSOM verwenden können, müssen Sie einen authentifizierten Clientkontext mittels der Microsoft.SharePointOnline.CSOM erhalten. Verwenden Sie dann den authentifizierten Clientkontext, um eine Instanz des AppManager-Objekts des PnP CSOM zu erhalten, um die ALM-Befehle aufzurufen:

using Microsoft.SharePoint.Client;
using OfficeDevPnP.Core.ALM;

// ...

using (var context = new ClientContext(webURL)) {
  context.Credentials = new SharePointOnlineCredentials(username, securePassword);
  var appManager = new AppManager(context);
  // execute PnP CSOM ALM command
}

Bei allen PnP-Kernmethoden wird davon ausgegangen, dass die Anforderung auf den Mandanten-App-Katalog in dem Mandanten abzielt, mit dem Sie sich über das ClientContext-Objekt des SharePoint-CSOM verbinden. Sie können den Bereich aller Befehle mit einem zusätzlichen Bereichsargument überschreiben, beispielsweise

appManager.Install('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx', AppCatalogScope.Site);

Hier finden Sie weitere Informationen: PnP PowerShell

PnP PowerShell

PnP PowerShell implementiert die ALM-APIs durch den Aufruf des PnP CSOM.

Bevor Sie eines der Cmdlets im PnP PowerShell-Modul verwenden, müssen Sie sich zuerst mittels des Connect-PnPOnline-Cmdlet mit SharePoint Online verbinden.

Bei allen PnP PowerShell-Cmdlets wird davon ausgegangen, dass die Anforderung auf den Mandanten-App-Katalog auf den Mandanten abzielt, mit dem Sie sich über das Connect-PnPOnline-Objekt des SharePoint-CSOM verbinden. Sie können den Bereich des Befehlt mittels dem -Scope-Parameter überschreiben, um den App-Katalog einer Websitesammlung anzusprechen.

Hier finden Sie weitere Informationen: PnP PowerShell

Hinweis

PnP PowerShell ist eine Open Source-Lösung mit aktiver Community, die Support dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

CLI für Microsoft 365

Das CLI für Microsoft 365 ist eine plattformübergreifende Befehlszeilenschnittstelle, die auf einer beliebigen Plattform verwendet werden kann, darunter Windows, macOS und Linux. Das CLI implementiert die ALM-APIs über den Aufruf des SharePoint-REST-APIs.

Bevor Sie einen der Befehle im CLI für Microsoft 365 verwenden, müssen Sie Ihren Microsoft 365-Mandanten zuerst über den Befehl m365 login verbinden.

Weitere Informationen finden Sie hier: CLI für Microsoft 365

Hinweis

Die CLI für Microsoft 365 ist eine Open-Source-Lösung mit aktiver Community, die Support dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Hinzufügen eines Lösungspakets

Fügen Sie zunächst einem App-Katalog ein App-Paket (*.sppkg oder *.app) hinzu, um es für SharePoint-Websites verfügbar zu machen.

HTTP-Anforderung

POST /_api/web/{scope}appcatalog/Add(overwrite=true, url='sharepoint-solution-package.sppkg')

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata
Content-Type application/json
X-RequestDigest {form digest}
binaryStringRequestBody true

Anforderungstext

Bytearray der Datei

Lösungspakete bereitstellen

Das Bereitstellen der Lösung macht sie für die Installation in Websites verfügbar.

HTTP-Anforderung

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Deploy

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata
Content-Type application/json;odata=nometadata;charset=utf-8
X-RequestDigest {form digest}

Anforderungstext

{
  "skipFeatureDeployment": true
}

Hinweis

Dieser Vorgang kann nur nach dem Aufruf des Add-Endpunkts und vor der Installation von Paketen auf bestimmten Websites abgeschlossen werden.

Wichtig

Das parallele Bereitstellen von mehreren Paketen wird nicht unterstützt. Stellen Sie sicher, dass Sie Ihre Bereitstellungsvorgänge serialisieren, um Bereitstellungsfehler zu vermeiden.

Lösungspakete zurückziehen

Dies ist das Gegenteil des Bereitstellen-Schrittes von oben. Nach dem Zurückziehen kann die Lösung nicht mehr in Websites installiert werden.

HTTP-Anforderung

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Retract

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata
X-RequestDigest {form digest}

Hinweis

Dieser Vorgang wird die Installation der Lösung in Websites blockieren und bestehende Installationen deaktivieren.

Lösungspakete entfernen

Dies ist das Gegenteil des Hinzufügen-Schrittes von oben. Nach dem Entfernen aus dem App-Katalog kann die Lösung nicht bereitgestellt werden.

HTTP-Anforderung

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Remove

Hinweis

Wenn der Vorgang „Zurückziehen“ nicht vor der Vorgang „Entfernen“ ausgeführt wird, wird die Lösung automatisch zurückgezogen.

Verfügbare Pakete auflisten

Dieser Vorgang wird eine Liste aller verfügbaren SharePoint-Framework-Lösungen oder -Add-Ins im App-Katalog zurückgeben.

HTTP-Anforderung

GET /_api/web/{scope}appcatalog/AvailableApps

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata

Antwort

{
  "value": [
    {
      "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
      "ContainsTenantWideExtension": false,
      "CurrentVersionDeployed": true,
      "Deployed": true,
      "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
      "IsClientSideSolution": true,
      "IsEnabled": true,
      "IsPackageDefaultSkipFeatureDeployment": false,
      "IsValidAppPackage": true,
      "ShortDescription": "",
      "SkipDeploymentFeature": false,
      "Title": "sharepoint-solution-package"
    },
    {
      "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
      "ContainsTenantWideExtension": false,
      "CurrentVersionDeployed": true,
      "Deployed": true,
      "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
      "IsClientSideSolution": true,
      "IsEnabled": true,
      "IsPackageDefaultSkipFeatureDeployment": false,
      "IsValidAppPackage": true,
      "ShortDescription": "",
      "SkipDeploymentFeature": false,
      "Title": "sharepoint-solution-package2"
    }
  ]
}

Abrufen einer bestimmten Lösung

Diese Aktion wird Details über eine bestimmte SharePoint-Framework-Lösung oder ein bestimmtes -Add-In zurückgeben, die/das im App-Katalog verfügbar ist.

HTTP-Anforderung

GET /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata

Antwort

{
  "AadAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "ContainsTenantWideExtension": false,
  "CurrentVersionDeployed": true,
  "Deployed": true,
  "ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "IsClientSideSolution": true,
  "IsEnabled": true,
  "IsPackageDefaultSkipFeatureDeployment": false,
  "IsValidAppPackage": true,
  "ShortDescription": "",
  "SkipDeploymentFeature": false,
  "Title": "sharepoint-solution-package"
}

Lösungspaket in einer Website installieren

Installieren Sie ein Lösungspaket mit einem bestimmten Bezeichner aus dem App-Katalog in eine auf URL-Kontext basierende Website.

HTTP-Anforderung

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Install

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata
X-RequestDigest {form digest}

Installierte Lösungspakete upgraden

Aktualisieren Sie ein Lösungspaket der Website auf eine neuere, im App-Katalog verfügbare Version.

HTTP-Anforderung

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Upgrade

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata
X-RequestDigest {form digest}

Lösungspakete von einer Website deinstallieren

Diese Aktion ist das Gegenteil des Installieren-Befehls von oben.

Hinweis

Wenn Sie ein Lösungspaket mit einer der folgenden Methoden von der Website deinstallieren, wird es dauerhaft gelöscht; es wird nicht in den Papierkorb gelegt.

HTTP-Anforderung

POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Uninstall

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata
X-RequestDigest {form digest}

Synchronisieren einer Lösung mit dem Microsoft Teams-App-Katalog

Diese Aktion setzt voraus, dass Sie auf die Listenelement-ID der Lösung auf der App-Katalogwebsite verweisen.

HTTP-Anforderung

POST /_api/web/{scope}appcatalog/SyncSolutionToTeams(id=xxxxx)

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}
Accept application/json;odata=nometadata
X-RequestDigest {form digest}

Siehe auch