APIs do ALM (Gerenciamento do Ciclo de Vida do Aplicativo)

As APIs do ALM fornecem APIs simples para gerenciar a implantação de soluções e suplementos da Estrutura do SharePoint no seu locatário. As APIs do ALM dão suporte às seguintes funcionalidades:

• Adicione a solução do SharePoint Framework ou o Suplemento do SharePoint ao catálogo de aplicativos do locatário ou do conjunto de sites.
• Remova a solução do SharePoint Framework ou o Suplemento do SharePoint do catálogo de aplicativos do locatário ou do conjunto de sites.
• Habilite a solução do SharePoint Framework ou do Suplemento do SharePoint para que ela fique disponível para instalação no catálogo de aplicativos do locatário ou do conjunto de sites.
• Desabilite a solução do SharePoint Framework ou do Suplemento do SharePoint para que ela não fique disponível para instalação no catálogo de aplicativos do locatário ou do conjunto de sites.
• Instale a solução do SharePoint Framework ou o Suplemento do SharePoint do catálogo de aplicativos do locatário ou do conjunto de sites em um site.
• Atualize a solução do SharePoint Framework ou o Suplemento do SharePoint para um site que tenha uma versão mais recente disponível no catálogo de aplicativos do locatário ou do conjunto de sites.
• Desinstalar a solução da Estrutura do SharePoint ou o suplemento do SharePoint do site.
• Liste tudo e obtenha detalhes sobre soluções do SharePoint Framework ou Suplementos do SharePoint no catálogo de aplicativos do locatário ou do conjunto de sites.

As APIs do ALM podem ser usadas para executar exatamente as mesmas operações que estão disponíveis na perspectiva da interface. Quando essas APIs são usadas, todas as ações típicas são executadas. A seguir estão algumas das características das APIs do ALM:

• Os eventos Install e UnInstall são disparados para suplementos hospedados pelo provedor quando ocorrem as operações correspondentes.
• As APIs do ALM dão suporte apenas a operações baseadas em aplicativo para soluções da Estrutura do SharePoint.

As APIs do ALM são compatíveis com os conjuntos de sites com escopo de locatário e catálogo de aplicativos do conjunto de sites. Use a URL do catálogo de aplicativos correspondente para direcionar um catálogo de aplicativos específico. Primeiro, você deve habilitar um catálogo de aplicativos de conjunto de sites antes de direcioná-lo com as ações documentadas nesta página.

Importante

As permissões no escopo do locatário que exigem permissões administrativas do locatário não têm suporte com as APIs do ALM.

Opções para trabalhar com APIs do ALM

As APIs ALM são fornecidas nativamente usando APIs REST, mas há extensões adicionais de modelo de objeto do lado do cliente (CSOM), cmdlets do PowerShell e a CLI multiplataforma para Microsoft 365 disponíveis por meio de canais da Comunidade PnP do Microsoft Office SharePoint Online.

API REST do Microsoft Office SharePoint Online

As APIs do ALM são fornecidas nativamente como pontos de extremidade na API REST do Microsoft Office SharePoint Online.

O catálogo de aplicativos deve ser incluído em todas as solicitações HTTP ao usar a API REST, conforme mostrado nos exemplos abaixo. Substitua o espaço reservado {app-catalog-scope} no ponto de extremidade pelo escopo do catálogo de aplicativos. As opções de escopo disponíveis são tenantappcatalog e sitecollectionappcatalog.

Por exemplo:

Escopo	Ponto de extremidade
locatário	https://contoso.sharepoint.com/sites/AppCatalog/_api/web/tenantappcatalog/{command}
conjunto de sites	https://contoso.sharepoint.com/sites/Marketing/_api/web/sitecollectionappcatalog/{command}

• ao direcionar o catálogo de aplicativos de locatário localizado em https://contoso.sharepoint.com/sites/AppCatalog, o ponto de extremidade seria **

Saiba mais aqui: API REST do Microsoft Office SharePoint Online

PnP CSOM (também conhecido como: PnP Sites Core)

O CSOM PnP implementa as APIs do ALM chamando a API REST do Microsoft Office SharePoint Online.

Antes de usar qualquer uma das APIs do ALM no PnP CSOM, você precisa obter um contexto de cliente autenticado usando o Microsoft.SharePointOnline.CSOM. Em seguida, use o contexto do cliente autenticado para obter uma instância do objeto AppManager PnP CSOM para chamar os comandos 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
}

Em todos os métodos PnP Core, supõe-se que a solicitação seja direcionada ao catálogo de aplicativos de locatário no locatário ao qual você se conecta usando o objeto CSOM do Microsoft Office SharePoint OnlineClientContext. você pode substituir o escopo de todos os comandos por um argumento de escopo opcional, por exemplo

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

Saiba mais aqui: PowerShell PnP

PowerShell PnP

O PowerShell PnP implementa as APIs do ALM chamando o CSOM PnP.

Antes de usar qualquer um dos cmdlets no módulo PowerShell PnP, você deve primeiro se conectar ao Microsoft Office SharePoint Online usando o cmdlet Connect-PnPOnline.

Em todos os cmdlets do PowerShell PnP, supõe-se que a solicitação seja direcionada ao catálogo de aplicativos de locatário no locatário ao qual você se conecta usando o cmdlet Connect-PnPOnline. Você pode substituir o escopo do comando usando o parâmetro -Scope para direcionar um catálogo de aplicativos de conjunto de sites.

Saiba mais aqui: PowerShell PnP

Observação

O PnP PowerShell é uma solução de software livre com uma comunidade ativa de suporte. Não há nenhuma SLA para o suporte da ferramenta de software livre por parte da Microsoft.

CLI para Microsoft 365

A CLI para Microsoft 365 é uma interface de linha de comando de plataforma cruzada que pode ser usada em qualquer plataforma, como Windows, MacOS e Linux. A CLI implementa as APIs do ALM chamando a API REST do Microsoft Office SharePoint Online.

Antes de usar qualquer um dos comandos na CLI para Microsoft 365, você deve primeiro conectar seu locatário Microsoft 365 usando o comando m365 login.

Saiba mais aqui: CLI para Microsoft 365

Observação

A CLI do Microsoft 365 é uma solução de software livre com uma comunidade ativa oferecendo suporte. Não há nenhuma SLA para o suporte da ferramenta de software livre por parte da Microsoft.

Adicionar pacote de solução

Primeiro, adicione um pacote de aplicativo (*.sppkg ou *.app) a um catálogo de aplicativos para disponibilizá-lo para sites do SharePoint.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata
Content-Type	application/json
X-RequestDigest	{form digest}
binaryStringRequestBody	true

Corpo da solicitação

Matriz de bytes do arquivo

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

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

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Implantar pacotes de solução

A implantação da solução a disponibiliza para instalação em sites.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata
Content-Type	application/json;odata=nometadata;charset=utf-8
X-RequestDigest	{form digest}

Corpo da solicitação

{
  "skipFeatureDeployment": true
}

Observação

Essa operação só pode ser concluída depois de chamar o ponto de extremidade Add e antes de instalar pacotes em sites específicos.

Importante

Não há suporte para a implantação de vários pacotes em paralelo. Certifique-se de serializar suas operações de implantação para evitar erros de implantação.

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

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

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Recolher pacotes de solução no catálogo de aplicativos

Esse é o inverso da etapa de implantação acima. Depois de cancelada, a solução não pode ser instalada em sites.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata
X-RequestDigest	{form digest}

Observação

Esta operação bloqueará a instalação da solução em sites e desabilitará as instalações existentes.

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

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

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Remover pacotes de solução do catálogo de aplicativos

Esse é o inverso da etapa adicionar acima. Depois de removida do catálogo de aplicativos, a solução não pode ser implantada.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

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

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Observação

Se a operação de Retração não for executada antes da de remoção, a solução será retraída automaticamente.

Listar pacotes disponíveis do catálogo de aplicativos

Esta operação retornará uma lista de todas as soluções ou suplementos disponíveis da Estrutura do SharePoint no catálogo de aplicativos.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata

Resposta

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

CSOM PnP

var allAppPackages = appManager.GetAvailable();

PowerShell PnP

Get-PnPApp

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

m365 spo app list

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Obtenha uma solução específica

Essa ação retornará detalhes sobre uma solução ou suplemento específico da Estrutura do SharePoint disponível no catálogo de aplicativos.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata

Resposta

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

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

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

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Instalar o pacote de solução em um site

Instale um pacote de solução com um identificador específico do catálogo de aplicativos no site com base no contexto da URL.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata
X-RequestDigest	{form digest}

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

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

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Atualizar pacotes de solução instalados

Atualize um pacote de solução do site para uma versão mais recente disponível no catálogo de aplicativos.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata
X-RequestDigest	{form digest}

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

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

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Desinstalar pacotes de solução de um site

Essa ação é o inverso do comando instalar acima.

Observação

Quando você usa o pacote de solução de desinstalação do site com qualquer um dos métodos abaixo, ele é excluído permanentemente; ele não é colocado na lixeira.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata
X-RequestDigest	{form digest}

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

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

Consulte a CLI para documentação do Microsoft 365 para obter detalhes completos e exemplos sobre este comando.

Sincronizar uma solução com o catálogo de aplicativos do Microsoft Teams

Essa ação requer que você consulte ID do item de lista da solução no site do catálogo de aplicativos.

API REST do Microsoft Office SharePoint Online

Solicitação HTTP

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	Bearer {token}
Aceitar	application/json;odata=nometadata
X-RequestDigest	{form digest}

CSOM PnP

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

PowerShell PnP

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

Consulte a Documentos do PnP PowerShell para obter detalhes completos e exemplos neste cmdlet.

CLI para Microsoft 365

Não Suportado

Confira também

• Conheça o serviço REST do SharePoint
• PowerShell PnP
• CLI para Microsoft 365