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
eUnInstall
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.
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
Implantar pacotes de solução
A implantação da solução a disponibiliza para instalação em sites.
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.
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.
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.
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.
Solicitação HTTP
POST /_api/web/{scope}appcatalog/AvailableApps/GetById('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx')/Remove
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.
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"
}
]
}
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.
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"
}
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.
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} |
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.
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} |
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.
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} |
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.
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} |