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 (obtenha o AccessPoint) — a API ativa a sua licença automaticamente através da sua identidade Entra, pelo que não é necessária qualquer chave de licença, a menos que o Suporte Realizer forneça uma para o seu tenant
• 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, Microsoft Defender for SQL ativado por predefinição). O servidor SQL é criado com prioridade Entra: o utilizador que efetua a implantação torna-se o administrador Entra inicial e nunca existe qualquer credencial SQL — não há nada para rodar ou desativar.

E-mails semanais de "Vulnerability Assessment scan completed" a mostrar verificações falhadas, mas nada no portal? Esperado num ambiente recém-implantado, não uma vulnerabilidade. O Microsoft Defender for SQL executa a Vulnerability Assessment clássica (baseada em storage), mas o painel Defender do portal Azure assume agora por predefinição a vista mais recente de configuração expressa, pelo que a hiperligação "View results" do e-mail pode chegar a uma vista sem quaisquer verificações. As verificações falhadas são verificações de baseline, que falham até o estado atual ser aprovado como baseline — o modelo pré-aprova a verificação determinística VA2065 (regras de firewall), mas uma verificação de rastreio de utilizadores, de baixa gravidade e específica do tenant, na base de dados da aplicação, não pode ser pré-declarada. Resolva uma vez: abra o servidor SQL (não a base de dados) → Microsoft Defender for Cloud → Vulnerability assessment → abra a verificação falhada → Approve as baseline → Scan novamente; os e-mails semanais seguintes reportarão todas as verificações aprovadas.

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), e um Tipo de implantação obrigatório, sem predefinição: escolha Nova instalação para uma implantação pela primeira vez, ou Atualizar instalação existente ao reimplantar sobre um AccessPoint já em execução — a postura de atualização preserva as definições de aplicação adicionadas pelo operador e não altera o acesso à base de dados. Opcionalmente, escolha um SKU do App Service (B1 para avaliação, S1 para produção padrão, P1v3 por predefinição; P2v3 quando as gravações forem transcodificadas em processo sem o módulo de processamento de media), um e-mail de alerta, e as capacidades opcionais abaixo. Deixe a chave API de licença em branco — o AccessPoint ativa a sua licença automaticamente através da identidade Entra da aplicação; introduza um valor apenas se o Suporte Realizer fornecer um para o seu tenant. 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.

Finish Setup (permissões do Graph). O próprio modelo nunca concede permissões do Graph. Após a implantação, abra a ligação finishSetupUrl nos Outputs da implantação e inicie sessão como Administrador Global — a página Finish Setup do editor concede, numa única passagem idempotente, todas as permissões do Graph de que a managed identity necessita. Reviste a mesma ligação após uma atualização, para obter as permissões recentemente introduzidas. Em seguida, execute um ciclo completo de Paragem/Arranque (Stop/Start) no App Service (não Restart), para que as permissões produzam efeito.

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 deteta automaticamente o tipo de implantação (nova instalação vs. atualização) e executa até sete passos — infraestrutura, autenticação SQL exclusiva do Entra (uma salvaguarda: os modelos atuais já criam o servidor com prioridade Entra), concessões de permissões do Graph (o equivalente com script à página Finish Setup), um ciclo de paragem/arranque do App Service, a storage entity opcional 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/2.1.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

# Backstop only: current templates create the SQL server Entra-first, so
# Entra-only auth is already in force and no SQL credential ever exists
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 destas permissões de aplicação do Microsoft Graph: Mail.Send, User.ReadBasic.All, TeamsAppInstallation.ReadForUser.All, Application.Read.All, AppCatalog.Read.All, e (ativada por predefinição, com opção de exclusão) AiEnterpriseInteraction.Read.All para a captura do Copilot. O caminho mais simples é a página Finish Setup — o output de implantação finishSetupUrl — que as concede todas numa única passagem idempotente, através do início de sessão delegado de um Administrador Global. Para as conceder por CLI:

$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" }
    # Copilot capture (tenant-wide) — granted by default; remove this line to opt out:
    @{ Name = "AiEnterpriseInteraction.Read.All";     Id = "839c90ab-5771-41ee-aef8-a562e8487c1e" }
)

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.

Capacidades opcionais

O modelo expõe várias capacidades opcionais, nenhuma necessária para executar o AccessPoint. Todas estão desativadas, a menos que as ative no momento da implantação, exceto a permissão de captura do Copilot, que é concedida por predefinição com opção de exclusão (o formulário Deploy to Azure, -p name=value no az deployment, ou os comutadores do Deploy-AccessPoint.ps1 indicados abaixo controlam-nas). Todos os recursos opcionais são implantados na sua própria assinatura Azure, com autenticação exclusiva por managed identity e acesso por chave desativado — nenhum dado de cliente sai do seu tenant, e a Microsoft não treina modelos com esses dados.

• Deploy AI Assist (Azure OpenAI) — adiciona um recurso Azure OpenAI à sua assinatura com autenticação por identidade gerida (sem chaves de API). A faturação é por utilização, pelo que um tenant inativo paga cerca de $0 e um departamento com atividade intensa gasta tipicamente valores de um só dígito em dólares por mês. Implantá-lo ativa as funcionalidades do AI Assist, cada uma comutável individualmente em Settings > Features. Cada resultado de IA é uma sugestão ou um rascunho editável — é sempre uma pessoa a decidir.

• Deploy AI Search (deployAiSearch=true) — adiciona o Azure AI Search para que a caixa de pesquisa de Documentos corresponda a palavras dentro dos documentos (texto extraído de PDF), além de nomes, tipos e etiquetas; com o AI Assist também implantado, suporta pesquisa semântica. Os novos documentos são indexados automaticamente, e uma varredura de Administrator (Settings > Setup > Document content search) indexa quaisquer documentos anteriores.

• Deploy Document Intelligence (deployDocumentIntelligence=true) — adiciona o Azure AI Document Intelligence para OCR: os documentos digitalizados apenas como imagem têm o seu texto lido, para que participem na pesquisa de conteúdo, na deteção de duplicados, nos resumos de IA e nas sugestões de redação, tal como qualquer outro documento. Também alimenta a deteção de texto no ecrã em vídeo (os fotogramas amostrados são lidos da mesma forma, faturados por fotograma). A faturação é por página (aproximadamente USD $1,50 por 1000 páginas). Sem ele, os documentos digitalizados continuam a corresponder por nome, tipo e etiquetas.

• Deploy Speech (deploySpeech=true) — adiciona o Azure AI Speech para transcrições e legendas de registos de vídeo e áudio: com marcação temporal e identificação de interlocutor, alimentando a pesquisa dentro da transcrição, a pesquisa de conteúdo, a deteção de duplicados, a fundamentação de IA e as propostas de redação ancoradas na transcrição. A conta Speech lê o áudio através da sua própria managed identity — não é emitido qualquer token de acesso partilhado. A faturação é por hora de áudio (aproximadamente USD $0,18) e cerca de $0 quando inativo.

• Deploy Defender for Storage (deployDefenderForStorage=true) — ativa a análise de malware do Microsoft Defender for Storage no momento do carregamento para a conta de documentos. A API espelha cada veredito no documento e bloqueia a pré-visualização, a reprodução, a transferência e a divulgação de qualquer ficheiro assinalado, o que torna a análise parte do controlo de divulgação dos ficheiros nativos divulgados tal como estão. Faturado por GB analisado, com um limite máximo definido por malwareScanCapGBPerMonth (predefinição 5000).

• Deploy media processing (deployMediaProcessing=true) — o executor de media à escala de produção: duas Storage Queues e um trabalho Container Apps escalável a zero que executa a imagem de trabalhador de media do editor, para que as transcodificações, as miniaturas e a renderização de divulgação saiam do App Service. O mesmo trabalho converte documentos do Office muito grandes e digitalizações. Sem ele, as gravações são processadas em processo no App Service (escolha P2v3 para appServiceSku). Faturado por segundo-vCPU enquanto um trabalho está em execução; cerca de $0 quando inativo. O trabalho obtém uma imagem de contentor apenas de código — nenhum dado de cliente transita alguma vez pelo registo. Para produção, espelhe a imagem para o seu próprio Azure Container Registry uma vez por versão e aponte mediaWorkerImage e mediaWorkerRegistryResourceId para ela, para que os trabalhos de media nunca dependam de o registo do editor estar acessível:

  az acr create --name <yourregistry> --resource-group <rg> --sku Basic
  az acr import --name <yourregistry> --source realizer.azurecr.io/accesspoint/media-worker:<apiVersion> --image accesspoint/media-worker:<apiVersion>
  # deploy with: mediaWorkerImage = <yourregistry>.azurecr.io/accesspoint/media-worker:<apiVersion>
  #              mediaWorkerRegistryResourceId = $(az acr show --name <yourregistry> --query id -o tsv)
  

  Volte a executar a importação quando atualizar — a tag acompanha a versão da API. As assinaturas com egress restrito têm de utilizar este caminho.

• SharePoint origin (sharePointOrigin=https://contoso.sharepoint.com) — adiciona uma regra CORS de blob para a sua origem SharePoint e permite que as gravações sejam reproduzidas diretamente a partir do Blob Storage, através de ligações de delegação de utilizador válidas por uma hora, em vez de serem transmitidas através da API, reduzindo o egress do App Service. Deixe em branco sob isolamento de rede.

• Permissão de captura do Copilot (AiEnterpriseInteraction.Read.All) — esta permissão do Graph, aplicada a todo o tenant, é concedida por predefinição, para que os custódios possam capturar o histórico de interações do Copilot através de Documents > Add from Microsoft 365, desde o início. É exclusivamente de aplicação (o Microsoft Graph não oferece uma variante delegada), mas o AccessPoint lê sempre apenas o histórico do Copilot do próprio utilizador com sessão iniciada. Os tenants que seguem o princípio do menor privilégio podem recusá-la com Deploy-AccessPoint.ps1 -DisableCopilotCapture (ou grantCopilotCapturePermission=false no modelo ARM/Bicep) e podem revogar a função de aplicação no Entra ID a qualquer momento; as cinco permissões standard do Graph indicadas acima não são afetadas.

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 para os seletores de pessoas e para as fontes de captura Add-from-Microsoft-365 — User.Read.All, Sites.Read.All, Files.Read.All, Mail.Read e Mail.Read.Shared (caixas de correio próprias e partilhadas/de admissão), Calendars.Read e Calendars.Read.Shared, Chat.Read, ChannelMessage.Read.All, Team.ReadBasic.All, Channel.ReadBasic.All (conversas e canais do Teams), Notes.Read e Notes.Read.All (OneNote), e OnlineMeetingRecording.Read.All, OnlineMeetingTranscript.Read.All, e OnlineMeetings.Read (gravações e transcrições de reuniões do Teams organizadas pelo utilizador). Os âmbitos .Shared nunca alargam o acesso por si só — o Graph continua a aplicar as permissões de caixa de correio Exchange já existentes de cada utilizador.

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" }
    @{ Resource = "Microsoft Graph"; Scope = "Mail.Read.Shared" }
    @{ Resource = "Microsoft Graph"; Scope = "Calendars.Read" }
    @{ Resource = "Microsoft Graph"; Scope = "Calendars.Read.Shared" }
    @{ Resource = "Microsoft Graph"; Scope = "Chat.Read" }
    @{ Resource = "Microsoft Graph"; Scope = "ChannelMessage.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Team.ReadBasic.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Channel.ReadBasic.All" }
    @{ Resource = "Microsoft Graph"; Scope = "Notes.Read" }
    @{ Resource = "Microsoft Graph"; Scope = "Notes.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "OnlineMeetingRecording.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "OnlineMeetingTranscript.Read.All" }
    @{ Resource = "Microsoft Graph"; Scope = "OnlineMeetings.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: Configuração do URL da API (normalmente automática)

O web part descobre o URL da API automaticamente. A API do AccessPoint regista automaticamente o seu endereço na plataforma Realizer quando valida a sua licença — poucos minutos após o arranque do App Service — e o web part obtém-no a partir daí. Na maioria das implantações, não há nada a fazer aqui.

Verificação: recarregue o web part — o painel principal é carregado em vez do pedido de configuração. Se a API acabou de ser implantada, a descoberta é bem-sucedida no carregamento de página seguinte, após a primeira validação de licença bem-sucedida.

Definir o URL da API manualmente (opcional)

Só necessita disto para substituir a descoberta — por exemplo, para fixar o web part a um domínio personalizado.

Opção A — painel Setup. Abra o web part, 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 clique em Save. O painel valida o HTTPS antes de guardar, e um URL manual tem precedência sobre a descoberta.

Opção B — storage entity (PowerShell). Fixe o URL numa storage entity AccessPoint_ApiUrl, que tem precedência sobre a descoberta. Desde janeiro de 2026, o SharePoint bloqueia as escritas no property bag no catálogo de aplicações no-script (centro de mensagens MC1186368), pelo que um administrador do SharePoint deve permiti-las uma vez, em todo o tenant, antes de a storage entity poder ser escrita:

# One-time (SharePoint admin): allow property-bag updates on no-script sites
Set-SPOTenant -AllowWebPropertyBagUpdateWhenDenyAddAndCustomizePagesIsEnabled $true

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

Passo 6: Importar um Pacote Jurisdicional

Aceda a Settings > Jurisdiction 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 a função de Administrator — a única função incorporada, que resolve sempre para todas as permissões. Todas as outras funções são definidas ao nível do tenant: importar um pacote jurisdicional semeia funções já prontas (como o Request Coordinator, a função de facto de responsável por acesso e privacidade), que pode renomear ou remodelar em Settings > Roles & Permissions. Aceda a Settings > Manage Users, clique em Add User, procure no seu diretório, e atribua pelo menos um Administrator e um coordinator; o acesso de Custodian, Contributor, Reviewer e Reader decorre automaticamente do trabalho que atribui às pessoas.

O AccessPoint está agora pronto a ser utilizado.

Atualizar o AccessPoint

O AccessPoint informa-o quando está disponível uma versão mais recente — não há nada a subscrever ou a verificar manualmente:

• Durante a validação de licença de rotina, a Realizer Platform reporta a versão mais recente publicada do AccessPoint (a versão mais recentemente promovida ao canal de lançamento para clientes). Nenhum dado de utilização ou de caso está envolvido nesta verificação.
• Quando a versão publicada é mais recente do que a que a sua API está a executar, os administradores veem um aviso de Atualização disponível no painel e em Configuração Inicial, mostrando os números da versão atual e da mais recente.
• Quando está atualizado (ou a executar uma compilação pré-lançamento mais recente do que o lançamento publicado), a Configuração Inicial mostra "Your AccessPoint API is up to date."

Para aplicar uma atualização:

1. Em Settings > Setup, clique em Deploy update to Azure. Isto abre o Azure Portal com o modelo ARM mais recente — o mesmo modelo utilizado na implantação inicial.
2. Escolha o tipo de implantação Upgrade existing installation. Isto preserva as definições de aplicação adicionadas pelo operador e não altera o acesso à base de dados; o esquema da base de dados é atualizado automaticamente no arranque da API (migração DacPac).
3. Atualize o pacote SPFx: carregue o accesspoint.sppkg mais recente para o seu App Catalog (Passo 2 acima). Atualize o pacote da aplicação Teams no Teams Admin Center se tiver sido lançado um novo accesspoint-teams.zip.
4. Reveja a página Finish Setup após a atualização — concede de forma idempotente quaisquer permissões Graph introduzidas desde a sua implantação original.
5. Se espelhar a imagem do trabalhador de media no seu próprio registo, importe a tag da nova versão antes ou logo após a atualização — o trabalho obtém a tag que corresponde a apiVersion.

O modo de atualização transporta as definições de aplicação adicionadas pelo operador através da reimplantação — por exemplo, Documents__EmailRenderEngine, um License__RealizerApiUrl personalizado, ou RateLimiting__RequestsPerMinute (o orçamento de pedidos de API por utilizador, com predefinição de 1200 por minuto). As definições geridas pelo modelo são reafirmadas para os valores do modelo.

Dados de amostra para tenants de avaliação. Para ambientes de demonstração e avaliação, um web part separado, AccessPoint DevTools (accesspoint-devtools.sppkg), pode repor um tenant e semear dados de amostra adequados à jurisdição — utilizadores fictícios, pedidos, atribuições e documentos gerados — com um Rebuild demo de um clique. Reutiliza a ligação de API da aplicação principal e declara as suas próprias permissões de API (aprove uma vez em SharePoint Admin > Advanced > API access). Não destinado a produção: os endpoints destrutivos de reposição só são ativados quando a definição do App Service DevTools:Enabled=true está configurada — implante o pacote apenas em tenants de desenvolvimento/demonstração.

Privacidade dos dados de notificação do Teams (opcional)

Todos os registos de pedidos, o PII do requerente, os documentos e o histórico de auditoria vivem apenas no seu próprio tenant. As notificações respeitam isso também. O AccessPoint entrega cada notificação em até três canais, e dois deles nunca saem do seu tenant: o feed na aplicação (servido a partir da sua própria API) e o email/Outlook (enviado a partir da sua própria caixa de correio partilhada via Mail.Send). O feed de atividades do Teams é o único canal que, no seu modo predefinido, envia (POST) um pequeno payload para a API da Realizer Platform — o que só existe porque o Microsoft Graph exige que uma notificação de atividade seja enviada pela aplicação que detém o manifesto do Teams. O editor não armazena nada disso e regista apenas os GUIDs do destinatário e do tenant, e as mesmas notificações continuam a chegar por email e na aplicação. Dois controlos restringem ou eliminam mesmo isto:

Minimizar (um interruptor). Em Settings > Setup > Teams Notifications, ative Minimise Teams notification content (privacy). O payload retransmitido passa então a substituir o título/texto de pré-visualização da notificação e o nome do utilizador que praticou a ação por indicadores de espaço reservado neutros, para que não saiam do tenant nomes de atribuições/tarefas, texto de notificação ou nomes pessoais — só continuam a transitar o tipo de atividade, o número do pedido e os identificadores de registo, para que a notificação possa ser encaminhada e ligar diretamente ao registo. O texto completo continua a ser mostrado no feed na aplicação. Não é necessária qualquer alteração ao manifesto. (Por baixo: a definição de tenant Notifications:TeamsMinimalPayload.)

Eliminar (auto-hospedar o relay). Um tenant que não possa enviar nenhum dado de notificação ao editor pode fazer com que a sua própria API chame o Graph diretamente com a sua identidade gerida, para que nada chegue a api.realizer.io:

1. Conceda TeamsActivity.Send (aplicação) à identidade gerida da API e dê consentimento de administrador — o Graph só permite que a aplicação que detém o manifesto do Teams envie notificações de atividade, pelo que a identidade que envia tem de corresponder ao webApplicationInfo.id do manifesto.
2. Aponte o manifesto do Teams para a sua própria aplicação. Em manifest.json, defina webApplicationInfo.id para o ID de cliente do registo de aplicação/identidade gerida da sua API (substituindo o ID da aplicação do editor), mantendo webApplicationInfo.resource como o domínio do site SharePoint. Carregue o ficheiro zip editado diretamente no Teams Admin Center — não utilize o "Sync to Teams" do SharePoint (este reescreve o webApplicationInfo).
3. Mude a API para o relay Direto — adicione a definição do App Service Notifications__TeamsRelayMode=Direct (predefinição/não definido = Publisher) e reinicie. A API passa então a chamar sendActivityNotification diretamente; a concessão à aplicação empresarial do editor deixa de ser necessária para as notificações.
4. Revalide — envie uma notificação de teste (confirme que a ligação direta funciona) e confirme que o separador pessoal do Teams ainda inicia sessão, já que alterou o webApplicationInfo.id.

O relay Direto mantém 100% do conteúdo das notificações dentro do tenant, mas implica manter um manifesto do Teams personalizado e voltar a dar consentimento sempre que o ID da aplicação mude. A maioria dos tenants que só precisam de suprimir texto livre e nomes pessoais deve, em vez disso, utilizar o interruptor Minimizar — sem alteração ao manifesto, e a notificação continua a ligar diretamente ao registo.

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 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.

Resolução de Problemas

O web part mostra "Token request previously failed". Trata-se de uma falha de token em cache do SharePoint Framework: a primeira tentativa do web part para obter um token de acesso falhou, e o SPFx volta a emitir a mensagem durante o resto da sessão do navegador, sem voltar a tentar — pelo que continua a aparecer depois de a causa ser corrigida, até a sessão da página ser totalmente atualizada. Quase sempre visto num tenant novo cujos pedidos de acesso à API pendentes ainda não foram aprovados. Corrija, por esta ordem: (1) no SharePoint Admin Center → Advanced → API access, aprove todos os pedidos pendentes do pacote AccessPoint — o crítico é o âmbito access_as_user da API AccessPoint/Realizer, sem o qual todas as chamadas falham; os âmbitos do Graph para os seletores Add-from-Microsoft-365 podem ser aprovados ao mesmo tempo. (2) Se a aprovação for bem-sucedida mas os tokens continuarem a falhar, verifique em Entra admin center → Enterprise applications a aplicação e qualquer política de Acesso Condicional que a bloqueie, e confirme que um Administrador Global ou de Aplicações efetuou a aprovação. (3) Atualize totalmente o navegador — feche o separador e abra a página de novo, ou termine e reinicie a sessão; uma navegação suave não é suficiente. A mesma mensagem aparece quando os cookies de terceiros estão bloqueados numa janela privada, porque o iframe de token oculto falha — tente novamente numa janela normal antes de um diagnóstico mais profundo.

O aviso "AccessPoint X is available (you're on Y)" persiste depois de implantar a atualização. Com a hospedagem run-from-package, o App Service em execução mantém o pacote antigo montado até o site reciclar. Se o próprio ciclo de reciclagem da implantação não se concretizou, a compilação anterior continua a servir e o aviso está correto. Reinicie o App Service (portal → App Service → Restart, ou az webapp restart -g <rg> -n app-accesspoint-<tenant>): a nova compilação monta-se ao arrancar, valida a sua licença, e o aviso desaparece no carregamento de página seguinte. Os modelos publicados após a versão 2.0.73 reafirmam as definições da aplicação com um carimbo por implantação depois de o pacote ser preparado, o que aciona sempre a reciclagem, pelo que isto só ocorre ao implantar com um modelo mais antigo.

Reimplantar o modelo falha com RoleAssignmentExists. O Azure permite apenas uma atribuição de função por principal, função e âmbito. As concessões do próprio modelo têm nomes determinísticos e são idempotentes, pelo que este erro significa que a mesma concessão também foi criada fora do modelo — normalmente à mão no portal ou com az role assignment create (por exemplo, ao conceder a si próprio Storage Blob Data Reader na conta de armazenamento de avaliação de vulnerabilidades para ver os resultados das análises, o que os modelos atuais já concedem automaticamente a quem implanta). Elimine a atribuição criada manualmente indicada no erro e volte a implantar; o modelo recria a concessão idêntica sob o seu nome gerido, pelo que nenhum acesso se perde:

# The error's ID is the assignment name
az role assignment list --all --query "[?name=='<id-from-error>']"
az role assignment delete --ids <full-assignment-resource-id>

As concessões de outras pessoas não são afetadas — o modelo gere apenas os seus próprios principais (a identidade da API, a identidade do servidor SQL, e quem implanta).

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 jurisdicionais 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.