API управления жизненным циклом приложений (ALM)

API ALM представляют собой простые API для управления развертыванием решений и надстроек SharePoint Framework в клиенте. Эти API поддерживают указанные ниже возможности.

• Добавление решения SharePoint Framework или надстройки SharePoint в каталог приложений клиента или семейства веб-сайтов.
• Удаление решения SharePoint Framework или надстройки SharePoint из каталога приложений клиента или семейства веб-сайтов.
• Обеспечение доступности решения SharePoint Framework или надстройки SharePoint для установки в каталоге приложений клиента или семейства веб-сайтов.
• Отключение возможности установки решения SharePoint Framework или надстройки SharePoint в каталоге приложений клиента или семейства веб-сайтов.
• Установка решения SharePoint Framework или надстройки SharePoint из каталога приложений клиента или семейства веб-сайтов на сайте.
• Обновление решения SharePoint Framework или надстройки SharePoint на сайте до более поздней версии, доступной в каталоге приложений клиента или семейства веб-сайтов.
• Удаление решения SharePoint Framework или надстройки SharePoint с сайта.
• Перечисление и получение всех сведений о решениях SharePoint Framework или надстройках SharePoint в каталоге приложений клиента или семейства веб-сайтов.

С помощью API ALM можно выполнять те же операции, что и в пользовательском интерфейсе. При использовании этих API выполняются все типичные действия. Ниже описаны некоторые характеристики API ALM.

• События Install и UnInstall вызываются для надстроек с размещением у поставщика при выполнении соответствующих операций.
• API ALM поддерживают операции только для приложений лишь в решениях SharePoint Framework.

API ALM поддерживаются для семейств веб-сайтов в области клиента и каталога приложений семейства веб-сайтов. Используйте URL-адрес соответствующего каталога приложений для выбора определенного каталога приложений. Сначала необходимо включить каталог приложений семейства веб-сайтов, прежде чем применять для него действия, описанные на этой странице.

Важно!

Разрешения на уровне клиента, требующие разрешений администратора клиента, не поддерживаются при работе с API ALM.

Параметры для работы с API ALM

API ALM изначально предоставляются с использованием REST API, но существуют дополнительные расширения клиентской объектной модели (CSOM), командлеты PowerShell и межплатформенный интерфейс командной строки для Microsoft 365, доступные в каналах сообщества SharePoint PnP.

REST API SharePoint

API ALM изначально предоставляются в качестве конечных точек в REST API SharePoint.

Каталог приложений должен быть включен во все HTTP-запросы при использовании REST API, как показано в примерах ниже. Замените заполнитель {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, конечная точка будет представлена в виде **

Дополнительные сведения: REST API SharePoint

CSOM PnP (другое название: PnP Sites Core)

CSOM PnP реализует API ALM путем вызова REST API SharePoint.

Перед использованием любого API ALM в CSOM PnP необходимо получить контекст клиента, прошедшего проверку подлинности, с помощью Microsoft.SharePointOnline.CSOM. Затем используйте контекст клиента, прошедшего проверку подлинности, чтобы получить экземпляр объекта AppManager CSOM PnP для вызова команд 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 предполагается, что запрос нацелен на каталог приложений в клиенте, к которому вы подключаетесь с помощью объекта ClientContext CSOM SharePoint. Вы можете переопределить область всех команд с помощью дополнительного аргумента области, например

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

Дополнительные сведения: PnP PowerShell

PnP PowerShell

PnP PowerShell реализует API ALM путем вызова CSOM PnP.

Перед использованием любого командлета в модуле PnP PowerShell сначала подключитесь к SharePoint Online с помощью командлета Connect-PnPOnline.

Во всех методах PnP PowerShell предполагается, что запрос нацелен на каталог приложений в клиенте, к которому вы подключаетесь с помощью командлета Connect-PnPOnline. Область команды можно переопределить с помощью параметра -Scope для выбора в качестве цели каталога приложений семейства веб-сайтов.

Дополнительные сведения: PnP PowerShell

Примечание.

PnP PowerShell — это решение с открытым исходным кодом, поддержка которого предоставляется активным сообществом. Для инструментов с открытым исходным кодом не существует соглашения об уровне обслуживания в отношении поддержки корпорацией Майкрософт.

CLI для Microsoft 365

CLI для Microsoft 365 — это кроссплатформенный интерфейс командной строки, который можно использовать на любой платформе, в том числе Windows, macOS и Linux. CLI реализует API ALM путем вызова REST API SharePoint.

Перед использованием любых команд в CLI для Microsoft 365 сначала необходимо подключиться к клиенту Microsoft 365 с помощью команды m365 login.

Дополнительные сведения: CLI для Microsoft 365

Примечание.

CLI для Microsoft 365 — это решение с открытым исходным кодом, поддерживаемое активным сообществом. SLA для поддержки инструмента с открытым исходным кодом со стороны Майкрософт отсутствует.

Добавление пакета решения

Сначала добавьте пакет приложения (*.sppkg или *.app) в каталог приложений, чтобы сделать его доступным для сайтов SharePoint.

REST API SharePoint

HTTP-запрос

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

Заголовки запросов

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

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

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Развертывание пакетов решений

Развертывание решения делает его доступным для установки на сайтах.

REST API SharePoint

HTTP-запрос

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

Заголовки запросов

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

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

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Отзыв пакетов решений

Это действие является обратным шагу развертывания, описанному выше. После отзыва решение будет невозможно установить на сайтах.

REST API SharePoint

HTTP-запрос

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

Заголовки запросов

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

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

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Удаление пакетов решений

Это действие является обратным шагу добавления, описанному выше. После удаления из каталога приложений решение будет невозможно развернуть.

REST API SharePoint

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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

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

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Примечание.

Если не отозвать решение перед его удалением, оно будет отозвано автоматически.

Перечисление доступных пакетов

Эта операция возвращает список всех доступных надстроек или решений SharePoint Framework в каталоге приложений.

REST API SharePoint

HTTP-запрос

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

Заголовки запросов

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

m365 spo app list

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Получение определенного решения

Это действие возвращает сведения о конкретной надстройке или решении SharePoint Framework, доступном в каталоге приложений.

REST API SharePoint

HTTP-запрос

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

Заголовки запросов

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

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

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Установка пакета решения на сайте

Установите пакет решения с определенным идентификатором из каталога приложений на сайте на основе контекста URL-адреса.

REST API SharePoint

HTTP-запрос

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

Заголовки запроса

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

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

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Обновление установленных пакетов решений

Обновите пакет решения на сайте до более новой версии, доступной в каталоге приложений.

REST API SharePoint

HTTP-запрос

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

Заголовки запросов

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

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

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Удаление пакетов решений с сайта

Это действие является обратным команде установки, описанной выше.

Примечание.

При удалении пакета решения с сайта любым из указанных ниже методов он удаляется окончательно, а не отправляется в корзину.

REST API SharePoint

HTTP-запрос

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

Заголовки запросов

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

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

Подробные сведения и примеры этой команды см. в документации по CLI для Microsoft 365.

Синхронизация решения c каталогом приложений Microsoft Teams

Это действие требует обращения к идентификатору элемента списка решения на сайте каталога приложения.

REST API SharePoint

HTTP-запрос

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

Заголовки запросов

Заголовок	Значение
Authorization	Bearer {token}
Accept	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

Подробные сведения и примеры этого командлета см. в документации по PnP PowerShell.

CLI для Microsoft 365

Не поддерживается

См. также

• Знакомство со службой REST в SharePoint
• PnP PowerShell
• CLI для Microsoft 365