应用程序生命周期管理 (ALM) API

ALM API 提供简单的 API，用于跨租户管理 SharePoint 框架解决方案和加载项的部署。 ALM API 支持以下功能：

• 将 SharePoint 框架解决方案或 SharePoint 加载项添加到租户或网站集应用程序目录。
• 将 SharePoint 框架解决方案或 SharePoint 加载项从租户或网站集应用程序目录中删除。
• 让 SharePoint 框架解决方案或 SharePoint 加载项在租户或网站集应用程序目录中可供安装。
• 让 SharePoint 框架解决方案或 SharePoint 加载项在租户或网站集应用程序目录中不可供安装。
• 将租户或网站集应用程序目录中的 SharePoint 框架解决方案或 SharePoint 加载项安装到网站。
• 将网站中的 SharePoint 框架解决方案或 SharePoint 加载项升级到租户或网站集应用程序目录中的更高版本。
• 从网站卸载 SharePoint 框架解决方案或 SharePoint 加载项。
• 列出租户或网站集应用程序目录中的所有 SharePoint 框架解决方案或 SharePoint 加载项，并获取它们的详细信息。

ALM API 可用于执行的操作与 UI 支持的操作完全一样。 使用这些 API 时，会执行所有典型操作。 下面介绍了 ALM API 的一些特征：

• 在相应操作发生时，对提供程序托管的加载项触发 Install 和 UnInstall 事件。
• ALM API 仅支持 SharePoint 框架解决方案的基于应用的操作。

租户范围的网站集和网站集应用程序目录支持 ALM API。 使用相应的应用目录的 URL 以特定应用目录为目标。 必须先启用网站集应用目录，然后才能使用此页上记录的操作将其作为目标。

重要

ALM API 不支持需要租户管理权限的租户范围内的权限。

用于使用 ALM API 的选项

ALM API 通过使用 REST API 本机提供，但也可以使用 SharePoint PnP 社区版渠道提供的其他客户端对象模型 (CSOM) 扩展、PowerShell Cmdlet 和跨平台适用于 Microsoft 365 的 CLI。

SharePoint REST API

ALM API 本机作为 SharePoint REST API 上的终结点提供。

使用 REST API 时，应用目录必须包含在所有 HTTP 请求中，如下面的示例所示。 将终结点中的 {app-catalog-scope} 占位符替换为应用目录的范围。 可用的作用域选项为 tenantappcatalog 和 sitecollectionappcatalog。

例如：

作用域	终结点
租户	https://contoso.sharepoint.com/sites/AppCatalog/_api/web/tenantappcatalog/{command}
网站集	https://contoso.sharepoint.com/sites/Marketing/_api/web/sitecollectionappcatalog/{command}

• 以位于 https://contoso.sharepoint.com/sites/AppCatalog 的租户应用目录为目标时，终结点为 **

在此处了解详细信息：SharePoint REST API

PnP CSOM（也称为：PnP 站点核心）

PnP CSOM 通过调用 SharePoint REST API 实现 ALM API。

在 PnP CSOM 中使用任何 ALM API 之前，需要使用 Microsoft.SharePointOnline.CSOM 获取经过身份验证的客户端上下文。 然后，使用经过身份验证的客户端上下文获取 PnP CSOM 的 AppManager 对象的实例，以调用 ALM 命令：

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
}

在所有 PnP Core 方法中，假定该请求面向使用 SharePoint CSOM ClientContext 对象连接到的租户中的租户应用目录。 可以使用可选作用域参数替代所有命令的范围，例如

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

在此处了解详细信息：PnP PowerShell

PnP PowerShell

PnP PowerShell 通过调用 PnP CSOM 实现 ALM API。

在使用 PnP PowerShell 模块中的任何 cmdlet 之前，必须先使用 Connect-PnPOnline cmdlet 连接到 SharePoint Online。

在所有 PnP PowerShell cmdlet 中，假定该请求面向使用 Connect-PnPOnline cmdlet 连接到的租户中的租户应用目录。 可以使用 -Scope 参数替代命令的作用域，以定位网站集应用目录。

在此处了解详细信息：PnP PowerShell

注意

PnP PowerShell 是一种开放源代码解决方案，其中包含为其提供支持的活动社区。 没有用于 Microsoft 开放源代码工具支持的 SLA。

适用于 Microsoft 365 的 CLI

适用于 Microsoft 365 的 CLI 是跨平台命令行接口，可用于任何平台，包括 Windows、MacOS、Linux。 CLI 通过调用 SharePoint REST API 实现 ALM API。

在使用适用于 Microsoft 365 的 CLI 的任何命令之前，必须先使用 m365 login 命令连接 Microsoft 365 租户。

在此处了解详细信息：适用于 Microsoft 365 的 CLI

注意

CLI for Microsoft 365是一种开放源代码解决方案，其中包含为其提供支持的活动社区。 没有用于 Microsoft 开放源代码工具支持的 SLA。

添加解决方案包

首先将应用程序包 (*.sppkg 或 *.app) 添加到应用程序目录，以便使其可用于 SharePoint 网站。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata
Content-Type	application/json
X-RequestDigest	{form digest}
binaryStringRequestBody	true

请求正文

文件的字节数组

PnP CSOM

// read file
var filePath = "c:\path\to\file\sharepoint-solution-package.sppkg";
// get an instance of the PnP CSOM's AppManager as shown above
var result = appManager.Add(filePath);

PnP PowerShell

Add-PnPApp -Path ./sharepoint-solution-package.sppkg

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app add --filePath ./sharepoint-solution-package.sppkg

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

部署解决方案包

解决方案的部署使其可用于在站点中安装。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata
Content-Type	application/json;odata=nometadata;charset=utf-8
X-RequestDigest	{form digest}

请求正文

{
  "skipFeatureDeployment": true
}

注意

此操作只能在调用 Add 终结点后完成，然后才能将包安装到特定站点。

重要

不支持并行部署多个包。 请确保序列化部署操作以避免部署错误。

PnP CSOM

appManager.Deploy('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

PnP PowerShell

Publish-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app deploy --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

收回解决方案包

这是上述部署步骤的反函数。 收回后，无法在站点中安装解决方案。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata
X-RequestDigest	{form digest}

注意

此操作将阻止在站点中安装解决方案并禁用现有安装。

PnP CSOM

// get an app package
appManager.Retract('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

PnP PowerShell

Unpublish-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app retract --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

删除解决方案包

这是上述添加步骤的反函数。 已从应用目录中删除，无法部署解决方案。

SharePoint REST API

HTTP 请求

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

PnP CSOM

appManager.Remove('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

PnP PowerShell

Remove-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app remove --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

注意

如果未在删除操作之前执行收回操作，则会自动收回解决方案。

列出可用包

此操作将返回应用程序目录中所有可用的 SharePoint 框架解决方案或加载项的列表。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata

响应

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

PnP CSOM

var allAppPackages = appManager.GetAvailable();

PnP PowerShell

Get-PnPApp

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app list

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

获取特定解决方案

此操作将返回有关应用程序目录中提供的特定 SharePoint 框架解决方案或加载项的详细信息。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata

响应

{
  "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"
}

PnP CSOM

var appPackage = appManager.GetAvailable('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx');

PnP PowerShell

Get-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app get --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

在站点中安装解决方案包

根据 URL 上下文，将应用程序目录中具有特定标识符的解决方案包安装到网站。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata
X-RequestDigest	{form digest}

PnP CSOM

// get an app package
appManager.Install('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

PnP PowerShell

Install-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app install --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

升级已安装的解决方案包

将网站中的解决方案包升级到应用程序目录中可用的更高版本。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata
X-RequestDigest	{form digest}

PnP CSOM

// get an app package
var appPackage = appManager.GetAvailable('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx');
if (appPackage.CanUpgrade) {
  appManager.Upgrade(appPackage)
}

PnP PowerShell

Update-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app upgrade --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

从站点卸载解决方案包

此操作是对上述安装命令的反操作。

注意

使用以下任何方法从站点卸载解决方案包时，它将被永久删除；它未放置在回收站中。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata
X-RequestDigest	{form digest}

PnP CSOM

appManager.Uninstall('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

PnP PowerShell

Uninstall-PnPApp -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

m365 spo app uninstall --id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx --siteUrl <url>

有关此命令的完整详细信息和示例，请参阅适用于 Microsoft 365 文档的 CLI。

将解决方案与 Microsoft Teams 应用目录同步

此操作要求你引用应用目录站点中该解决方案的列表项 ID。

SharePoint REST API

HTTP 请求

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

请求标头

标头	值
Authorization	Bearer {token}
接受	application/json;odata=nometadata
X-RequestDigest	{form digest}

PnP CSOM

appManager.SyncToTeams('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')

PnP PowerShell

Sync-PnPAppToTeams -Identity xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

有关此 cmdlet 的完整详细信息和示例，请参阅 PnP PowerShell 文档。

适用于 Microsoft 365 的 CLI

不支持

另请参阅

• 了解 SharePoint REST 服务
• PnP PowerShell
• 适用于 Microsoft 365 的 CLI