Guia de Implantação

O AccessPoint utiliza um modelo de implantação dividido: um web part SPFx leve no SharePoint, uma aplicação Teams que aloja o mesmo web part como separador pessoal, e um backend Azure que executa a API e armazena todos os dados. Cada componente é implantado no seu próprio tenant Microsoft 365 e assinatura Azure — nada é alojado pelo editor, e nenhum dado de cliente sai do seu ambiente.

Visão Geral

Para nuvens soberanas/governamentais, fixação de versão ou implantações com scripts, todos os artefactos são também publicados em https://get.realizer.io/public/accesspoint/latest/.

A ordem de instalação é importante. Instale a solução SharePoint antes de qualquer utilizador abrir o separador pessoal do Teams. A aplicação Teams carrega o web part SPFx a partir do SharePoint num iframe — sem isso, os utilizadores veem uma página 404 do SharePoint dentro do Teams.

Pré-requisitos

• Uma assinatura AccessPoint ativa e uma chave API de licença (obtenha o AccessPoint)
• Uma assinatura Azure com direitos de Colaborador (ou superiores) no grupo de recursos de destino
• Um SharePoint App Catalog aprovisionado no seu tenant, mais direitos de Administrador do SharePoint
• Administrador Global ou Administrador de Aplicações no Entra ID para concessões de permissões do Graph e consentimento de administrador
• Administrador do Teams (ou Administrador Global) para publicar a aplicação Teams
• Para implantações com script ou manuais: Azure CLI (com sessão iniciada através de az login como utilizador, não como service principal) e o módulo PnP.PowerShell

Não existe qualquer dependência de nível de licenciamento do Microsoft 365, do Power Platform ou do Dataverse — qualquer utilizador com acesso ao SharePoint ou ao Teams pode utilizar o AccessPoint.

Passo 1: Implantar os Recursos Azure

Este passo aprovisiona o backend: um App Service Linux (a API), uma base de dados Azure SQL, Blob Storage e Application Insights com Log Analytics. Os recursos são denominados {type}-accesspoint-{tenantName} (por exemplo, app-accesspoint-contoso) e são reforçados por predefinição (TLS 1.3, autenticação SQL exclusiva do Entra, FTPS e autenticação básica desativados).

Opção A: Azure Portal (recomendado). Implante o modelo Bicep/ARM do AccessPoint com um clique a partir do Azure Portal (o botão Deploy to Azure). O formulário de implantação recolhe a sua assinatura e grupo de recursos, o nome do tenant (por exemplo, contoso a partir de contoso.sharepoint.com), a chave API de licença, o SKU do App Service (B1 para avaliação, S1 para produção padrão, P1v3 por predefinição), um e-mail de alerta opcional, e um interruptor Grant Graph Permissions (ativado por predefinição; requer Administrador de Aplicações). O pacote da API é implantado automaticamente no App Service — após a implantação, não existe qualquer dependência de tempo de execução relativamente a serviços externos.

Opção B: Bicep + PowerShell. Para pipelines personalizados ou controlo de alterações rigoroso, execute o script de implantação em relação ao modelo ARM publicado:

Invoke-WebRequest -Uri "https://get.realizer.io/public/accesspoint/latest/Deploy-AccessPoint.ps1" -OutFile "Deploy-AccessPoint.ps1"

# End-to-end: infrastructure, configuration, and both apps
.\Deploy-AccessPoint.ps1 `
    -SharePointSiteUrl "https://contoso.sharepoint.com/sites/accesspoint" `
    -TemplateUri "https://get.realizer.io/public/accesspoint/latest/main.json" `
    -DeploySharePointApp -DeployTeamsApp

O script executa até sete passos — infraestrutura, autenticação SQL exclusiva do Entra, concessões de permissões do Graph, um ciclo de paragem/arranque do App Service, a storage entity do SharePoint (URL da API), aprovações de permissões de API do SPFx, e instalações opcionais das aplicações. Cada um pode ser ignorado de forma independente (-SkipInfrastructure, -SkipGraphPermissions, -SkipSharePoint). Fixe uma versão com -ArtifactBaseUrl "https://get.realizer.io/public/accesspoint/1.0.0" para implantações reprodutíveis e com integridade verificada (o script verifica o SHA-256 publicado e aborta em caso de incompatibilidade).

Para executar as componentes de infraestrutura você mesmo:

$TenantName    = "contoso"
$ResourceGroup = "rg-accesspoint-$TenantName"

az group create --name $ResourceGroup --location "canadacentral"

$deployment = az deployment group create `
    --resource-group $ResourceGroup `
    --template-uri "https://get.realizer.io/public/accesspoint/latest/main.json" `
    --parameters tenantName=$TenantName appServiceSku=P1v3 `
    --output json | ConvertFrom-Json

$appName     = $deployment.properties.outputs.appServiceName.value
$apiUrl      = $deployment.properties.outputs.appServiceUrl.value
$principalId = $deployment.properties.outputs.appServicePrincipalId.value

# Disable SQL password auth — Entra ID (managed identity) only
az sql server ad-only-auth enable --resource-group $ResourceGroup `
    --server-name $deployment.properties.outputs.sqlServerName.value

Concessões de permissões do Graph. A managed identity do App Service necessita de cinco permissões de aplicação do Microsoft Graph: Mail.Send, User.ReadBasic.All, TeamsAppInstallation.ReadForUser.All, Application.Read.All e AppCatalog.Read.All. O modelo concede-as automaticamente (grantGraphPermissions=true, a predefinição) quando o utilizador que efetua a implantação tem a função de Administrador de Aplicações ou AppRoleAssignment.ReadWrite.All. Caso contrário, conceda-as posteriormente:

$graphSpId = az ad sp show --id "00000003-0000-0000-c000-000000000000" --query id -o tsv

$permissions = @(
    @{ Name = "Mail.Send";                            Id = "b633e1c5-b582-4048-a93e-9f11b44c7e96" }
    @{ Name = "User.ReadBasic.All";                   Id = "97235f07-e226-4f63-ace3-39588e11d3a1" }
    @{ Name = "TeamsAppInstallation.ReadForUser.All"; Id = "9ce09611-f4f7-4abd-a629-a05450422a97" }
    @{ Name = "Application.Read.All";                 Id = "9a5d68dd-52b0-4cc2-bd40-abcf44ac3a30" }
    @{ Name = "AppCatalog.Read.All";                  Id = "e12dae10-5a57-4817-b79d-dfbec5348930" }
)

foreach ($perm in $permissions) {
    $bodyFile = [System.IO.Path]::GetTempFileName()
    @{ principalId = $principalId; resourceId = $graphSpId; appRoleId = $perm.Id } |
        ConvertTo-Json | Set-Content -Path $bodyFile -Encoding utf8
    az rest --method POST `
        --uri "https://graph.microsoft.com/v1.0/servicePrincipals/$principalId/appRoleAssignments" `
        --body "@$bodyFile" --headers "Content-Type=application/json" --output none
    Remove-Item $bodyFile
}

# Full stop/start (NOT restart) clears the managed identity token cache
az webapp stop  --name $appName --resource-group $ResourceGroup
Start-Sleep -Seconds 10
az webapp start --name $appName --resource-group $ResourceGroup

Verificação: aceda a https://<api-url>/api/health e confirme uma resposta saudável.

Passo 2: Instalar as Aplicações AccessPoint

Instale primeiro a solução SharePoint, e depois a aplicação Teams.

Solução SharePoint. A partir da página no AppSource, clique em Get it now e aprove-a no seu SharePoint App Catalog, implantada em todo o tenant. Em alternativa, carregue-a manualmente (SharePoint Admin Center > More features > Apps > Upload, marque "Make this solution available to all sites") ou deixe que o script o faça.

Aplicação Teams. A partir da página no AppSource, clique em Get it now e aprove-a no Teams Admin Center, ou instale ambas as aplicações através do script (o utilizador com sessão iniciada necessita de ser administrador do SharePoint, além de administrador do Teams ou Administrador Global):

.\Deploy-AccessPoint.ps1 `
    -SharePointSiteUrl "https://contoso.sharepoint.com/sites/accesspoint" `
    -SkipInfrastructure -SkipGraphPermissions `
    -DeploySharePointApp -DeployTeamsApp

NÃO utilize a funcionalidade "Sync to Teams" do SharePoint. Esta substitui silenciosamente o webApplicationInfo.id do manifesto, o que quebra as notificações do feed de atividades do Teams. Carregue a aplicação Teams diretamente no Teams Admin Center.

Verificação: a solução aparece no catálogo de aplicações sem erros, e o AccessPoint aparece como Allowed em Teams Admin Center > Manage apps.

Passo 3: Aprovar as Permissões da API

O pacote SPFx solicita permissões delegadas que um administrador do SharePoint deve aprovar. No SharePoint Admin Center, aceda a Advanced > API access e aprove cada pedido pendente do AccessPoint (access_as_user na API do AccessPoint, além de âmbitos do Graph como User.Read.All, Sites.Read.All, Files.Read.All, Mail.Read).

Ou aprove através do PnP PowerShell:

Connect-PnPOnline -Url "https://contoso-admin.sharepoint.com" -Interactive

$spfxPermissions = @(
    @{ Resource = "ed19c96c-a7c5-4dca-8b47-0899c406329f"; Scope = "access_as_user" }
    @{ Resource = "Microsoft Graph"; Scope = "User.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Sites.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Files.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Mail.Read" }
)
foreach ($perm in $spfxPermissions) {
    Grant-PnPTenantServicePrincipalPermission -Scope $perm.Scope -Resource $perm.Resource
}

Por fim, um Administrador Global concede o consentimento de administrador para a aplicação multi-tenant do editor, abrindo https://login.microsoftonline.com/common/adminconsent?client_id=ed19c96c-a7c5-4dca-8b47-0899c406329f num navegador.

Verificação: a página de acesso à API não apresenta pedidos pendentes do AccessPoint.

Passo 4: Utilizar o AccessPoint no SharePoint ou no Teams

SharePoint: edite ou crie uma página, clique em +, procure por AccessPoint, adicione o web part e publique.

Teams: os utilizadores encontram o AccessPoint em Apps > Built for your org (a indexação da pesquisa pode demorar entre 15 minutos e várias horas após a primeira instalação). Opcionalmente, fixe-o para todos através de Teams Admin Center > App setup policies, adicionando o AccessPoint a Installed apps e Pinned apps.

Passo 5: Configurar o URL da API

Abra o web part e aceda a Settings > Setup. Introduza o API URL (o URL do App Service obtido no Passo 1, por exemplo, https://app-accesspoint-contoso.azurewebsites.net) e o Client ID do registo de aplicação Entra ID da API e, em seguida, clique em Save. O painel valida o HTTPS e o formato GUID antes de guardar.

O script de implantação define a storage entity subjacente do SharePoint por si. Para a definir manualmente:

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive
$appCatalogUrl = Get-PnPTenantAppCatalogUrl
Connect-PnPOnline -Url $appCatalogUrl -Interactive   # storage entities live on the App Catalog site

Set-PnPStorageEntity -Key "AccessPoint_ApiUrl" -Value $apiUrl -Description "AccessPoint API base URL"
Get-PnPStorageEntity -Key "AccessPoint_ApiUrl"       # verify

Verificação: recarregue o web part — o painel principal é carregado em vez do pedido de configuração.

Passo 6: Importar um Pacote de Configuração

Aceda a Settings > Configuration Packs, escolha o pacote para a sua jurisdição (Canadá ATIA, EUA FOIA, UE GDPR, entre outros), e clique em Import. O pacote cria tipos de pedido, motivos de prorrogação, campos de escolha, modelos de notificação e traduções. Reveja e personalize os itens importados posteriormente.

Passo 7: Atribuir Funções de Utilizador

O primeiro utilizador a abrir o AccessPoint recebe automaticamente as funções de Administrador e SAO. Aceda a Settings > Manage Users, clique em Add User, procure no seu diretório e atribua funções: pelo menos um Administrador e um SAO, além das funções de Custódio, Contribuidor, Revisor e Leitor conforme necessário.

O AccessPoint está agora pronto a ser utilizado.

Implantação Multi-Tenant

Utilize este padrão quando o backend Azure reside num tenant Entra ID diferente do seu tenant Microsoft 365 — por exemplo, uma equipa de serviços partilhados que serve várias unidades de negócio, um MSP a alojar para clientes, ou tenants de Azure/M365 separados por motivos de governação. Uma única implantação pode servir vários tenants M365: a API isola os dados através do ID do tenant presente no token de cada utilizador, com filtros de consulta à base de dados limitados ao tenant e caminhos de blob prefixados com o tenant. Cada tenant M365 continua a necessitar da sua própria licença, da sua própria implantação SPFx e aprovações de permissões de API, e das suas próprias credenciais do Graph e caixa de correio de notificações.

Registo de aplicação do Graph. Uma managed identity só funciona no seu tenant de origem, pelo que deve criar um registo de aplicação single-tenant no tenant M365 (por exemplo, AccessPoint Graph Connector), conceder-lhe as mesmas cinco permissões de aplicação do Graph indicadas no Passo 1 com consentimento de administrador e, em seguida, criar um segredo de cliente e associá-lo ao App Service através do Key Vault:

# In the M365 tenant: create the client secret
$secret = az ad app credential reset --id $appId --display-name "AccessPoint" --years 2 --query password -o tsv

# In the Azure subscription: store the secret and reference it from the App Service
az keyvault secret set --vault-name $vaultName --name "GraphClientSecret" --value $secret

az webapp config appsettings set --resource-group $ResourceGroup --name $appName --settings `
    "Graph__TenantId=$m365TenantId" `
    "Graph__ClientId=$appId" `
    "Graph__ClientSecret=@Microsoft.KeyVault(SecretUri=https://$vaultName.vault.azure.net/secrets/GraphClientSecret)"

az webapp restart --resource-group $ResourceGroup --name $appName

Nunca armazene o segredo diretamente nas definições do App Service; a managed identity do App Service necessita da função Key Vault Secrets User no vault. Quando as três definições Graph__* estão presentes, a API utiliza o registo de aplicação; quando estão ausentes, recorre à managed identity para implantações no mesmo tenant.

Caixa de correio partilhada e política de acesso de aplicação. Crie uma caixa de correio partilhada sem licença no tenant M365 para as notificações por e-mail e restrinja Mail.Send para que a aplicação só possa enviar a partir dessa única caixa de correio:

Connect-ExchangeOnline -Organization "contoso.onmicrosoft.com"

New-Mailbox -Name "AccessPoint Notifications" -Alias "accesspoint-noreply" -Shared

New-DistributionGroup -Name "AccessPoint Mail Senders" -Type Security -ManagedBy "admin@contoso.com"
Add-DistributionGroupMember -Identity "AccessPoint Mail Senders" -Member "accesspoint-noreply@contoso.com"

New-ApplicationAccessPolicy -AppId $appId -PolicyScopeGroupId "AccessPoint Mail Senders" `
    -AccessRight RestrictAccess -Description "AccessPoint may send only from the shared mailbox"

# Verify (propagation can take up to 30 minutes)
Test-ApplicationAccessPolicy -AppId $appId -Identity "accesspoint-noreply@contoso.com"   # expect: Granted
Test-ApplicationAccessPolicy -AppId $appId -Identity "someother@contoso.com"             # expect: Denied

Cada tenant M365 repete depois os Passos 2 a 5 (aplicações, aprovações, URL da API — o mesmo URL da API serve todos os tenants). As notificações do feed de atividades do Teams requerem adicionalmente consentimento de administrador para a aplicação empresarial da Realizer e para a aplicação Teams instalada para os utilizadores; consulte Configuração Inicial para mais detalhes.

Reversão e Operações

Os mecanismos padrão do Azure cobrem a reversão: reimplante um pacote de API anterior a partir do histórico do Deployment Center do App Service, restaure o Azure SQL com restauro pontual (até 35 dias) e volte a carregar uma versão anterior do .sppkg no catálogo de aplicações. As importações de pacotes de configuração são aditivas e são revertidas através de um restauro da base de dados. Para o manual operacional completo — procedimentos detalhados de reversão, monitorização e tarefas de manutenção — contacte a nossa equipa de suporte.