> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-ingestion-api-migration.md).

# Migração para a Log Ingestion API

A Microsoft está a descontinuar a Log Analytics HTTP Data Collector API. Migre o RealmJoin para a DCR-based Logs Ingestion API com o módulo RealmJoin PowerShell.

## Visão geral

RealmJoin grava os seus registos de auditoria, operacionais e de runbook no seu próprio Log Analytics Workspace. Até agora, fazia isso através do Azure Monitor **API HTTP Data Collector**, que autentica com a chave partilhada do workspace.

A Microsoft termina o suporte para essa API em **14 de setembro de 2026**. O seu sucessor é a **API Logs Ingestion** (chamada *API Log Ingestion* no Portal RealmJoin), que se baseia em [Data Collection Rules (DCRs)](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/data-collection-rule-overview) e na autenticação Microsoft Entra ID em vez de uma chave partilhada. O RealmJoin suporta-a, e a mudança é efetuada com o [módulo PowerShell do RealmJoin](https://docs.realmjoin.com/pt/implementacao/onboarding-realmjoin-portal/advanced-setup.md).

{% hint style="info" %}
Esta página só se aplica se [Log Analytics](https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-analytics.md) já estiver configurado para o seu tenant. Se não estiver, não há nada a migrar — a mesma página de definições oferece um comando que configura imediatamente um workspace na API Log Ingestion. Ainda assim, recomendamos configurá-lo, para que os seus registos de auditoria, operacionais e de runbook fiquem armazenados no seu próprio tenant.
{% endhint %}

### Algo deixará de funcionar na data de desativação?

Muito provavelmente nada. A documentação atual da Microsoft descreve uma *suave* descontinuação: os pontos finais antigos deixam de ser suportados a partir dessa data, mas não deixam de aceitar dados, e a ingestão continua a funcionar desde que os clientes usem TLS 1.2 ou mais recente. A formulação mais rigorosa do anúncio original de 2023 — de que os pontos finais simplesmente ficariam indisponíveis — está desatualizada.

Ainda assim, a migração é recomendada: o caminho antigo não é suportado, depende de uma chave partilhada e não recebe mais correções.

### O que muda

{% columns %}
{% column %}

#### Antes — API Data Collector

* Autenticação com o **chave partilhada** ("Customer Workspace Key")
* Uma **registo de aplicação Entra ID pertencente ao cliente** com um segredo do cliente
* Tabelas `AuditLogs_CL`, `OperationalLogs_CL`, `RunbookLogs_CL`
* Configurado manualmente no Portal
  {% endcolumn %}

{% column %}

#### Depois — API Log Ingestion

* Autenticação com **Microsoft Entra ID**, sem chave partilhada
* O **Recursos Azure do RealmJoin** service principal, com âmbito limitado ao workspace e às suas regras
* Tabelas `RJAuditLogs_CL`, `RJOperationalLogs_CL`, `RJRunbookLogs_CL`
* Implementado e mantido pelo módulo PowerShell do RealmJoin
  {% endcolumn %}
  {% endcolumns %}

A migração reutiliza o seu **existente** workspace, por isso os seus registos existentes permanecem onde estão. O RealmJoin consulta as tabelas antigas e as novas lado a lado, o que significa que os dados históricos continuam visíveis no Portal após a migração.

### O que a migração implementa

Executar o comando de migração na sua subscrição cria:

* O **Recursos Azure do RealmJoin** service principal no seu tenant Entra ID (se ainda não existir)
* Três tabelas personalizadas no seu workspace existente: `RJAuditLogs_CL`, `RJOperationalLogs_CL`, `RJRunbookLogs_CL`
* Uma Data Collection Rule por tabela (`dcr-rj-aud-logs-*`, `dcr-rj-op-logs-*`, `dcr-rj-rb-logs-*`), cada uma com o seu próprio ponto final de ingestão direta
* Exatamente dois tipos de atribuição de função para o RealmJoin, e nada além disso:
  * **Leitor do Log Analytics** no workspace, para que o Portal possa consultar os seus registos
  * **Publicador de Métricas de Monitorização** em cada uma das três Data Collection Rules, para que o RealmJoin possa escrever nelas

O RealmJoin não recebe qualquer outra permissão na sua subscrição. A implementação é idempotente — executar novamente o mesmo comando é seguro e apenas aplica o que estiver em falta.

## Pré-requisitos

### No Portal RealmJoin

* Uma função que concede acesso à área de Definições (`CanReadSettingsDetails`, consulte [Permissões Disponíveis](https://docs.realmjoin.com/pt/administracao-e-definicoes/permission/custom-roles/available-permissions.md)). A página de Definições gera o comando de migração, incluindo um token de integração de curta duração.

### Na máquina que executa o PowerShell

* **PowerShell 7** ou posterior
* Acesso à [PowerShell Gallery](https://www.powershellgallery.com/packages/RealmJoin) para instalar o módulo RealmJoin
* O `Az.Accounts`, `Az.Resources` e `Az.Automation` módulos — o módulo RealmJoin instala-os automaticamente nas versões fixadas, para o utilizador atual

### Permissões da conta com a qual inicia sessão

* **Microsoft Entra ID:** permissão para criar service principals, por exemplo *Administrador de Aplicações*, *Administrador de Aplicações na Cloud* ou *Administrador Global*. Só é necessário na primeira vez, quando o service principal dos Recursos Azure do RealmJoin ainda não existe.
* **subscrição Azure:** permissão para implementar no grupo de recursos do workspace **e** para criar atribuições de função nele — por exemplo *Proprietário*, ou *Contribuidor* combinado com *Administrador de Acesso de Utilizador* / *Administrador de Controlo de Acesso Baseado em Funções*.
* O início de sessão ocorre através de `Connect-AzAccount`, que usa a aplicação **Azure PowerShell** de primeira parte. Tenants que restrinjam o consentimento do utilizador podem ter de conceder primeiro consentimento de administrador a essa aplicação.

{% hint style="info" %}
O grupo de recursos e o workspace do Log Analytics já existem no seu caso — a migração não os cria. Os comandos do Portal vêm pré-preenchidos com a sua subscrição, grupo de recursos e nome do workspace atuais.
{% endhint %}

## Onde executar os comandos

Execute os comandos numa **sessão local do PowerShell** numa estação de trabalho administrativa — da mesma forma que executaria o script de integração do RealmJoin.

{% hint style="warning" %}
Use uma **recém-aberta** sessão do PowerShell e evite **Azure Cloud Shell**. O módulo RealmJoin requer versões exatas dos módulos `Az.*` . Se já estiver carregada na sessão uma versão diferente de um `Az` módulo — o que normalmente acontece no Cloud Shell — o módulo não consegue recuperar e termina com uma mensagem de conflito de versões. Fechar a sessão e abrir uma nova resolve isto.
{% endhint %}

Não é necessária uma sessão elevada ("Executar como administrador"): os módulos são instalados com `-Scope CurrentUser`.

## Migração

{% stepper %}
{% step %}

#### Abra as definições do Log Analytics no Portal

Navegue até **Definições → Log Analytics** (<https://portal.realmjoin.com/settings/log-analytics-configuration>).

Enquanto o seu tenant ainda estiver na API Data Collector, a página mostra o aviso **"Migrar para a API Log Ingestion (Recomendado)"** juntamente com um bloco de comando pronto a copiar. Use o botão **Copiar** para o copiar.
{% endstep %}

{% step %}

#### Verifique o comando copiado

O comando tem este aspeto, com os seus próprios valores preenchidos:

```powershell
$latest = [version](Find-Module RealmJoin -Repository PSGallery -ErrorAction Stop).Version
if (-not (Get-Module -ListAvailable RealmJoin | Where-Object Version -ge $latest)) {
    Install-Module RealmJoin -Force -AllowClobber -ErrorAction Stop
}
Import-Module RealmJoin -Force
Set-RJLogAnalyticsWorkspace -ResourceGroupName "<ResourceGroupName>" -WorkspaceName "<WorkspaceName>" -SubscriptionId "<SubscriptionId>" -Token "<Token>" 6>&1
```

* As primeiras linhas instalam ou atualizam o módulo RealmJoin e importam-no.
* `Set-RJLogAnalyticsWorkspace` executa a migração real e regista o resultado com o RealmJoin usando o `-Token`.

{% hint style="warning" %}
Certifique-se de que `-ResourceGroupName`, `-WorkspaceName` e `-SubscriptionId` estão presentes e apontam para o seu **existente** workspace. Se `-WorkspaceName` estiver em falta, o módulo cria um **novo** workspace em vez de migrar o existente, e os seus registos antigos e novos acabam em locais diferentes. Adicione manualmente o parâmetro em falta, se necessário.
{% endhint %}

{% hint style="info" %}
**Sobre `6>&1`:** estes comandos comunicam o seu progresso no fluxo de Informação do PowerShell. A `6>&1` redireção mostra essa saída na consola — sem ela não verá quaisquer mensagens de progresso.
{% endhint %}
{% endstep %}

{% step %}

#### Execute o comando

Cole o bloco numa nova sessão do PowerShell e execute-o. O token é válido por cerca de uma hora — se tiver expirado, recarregue a página de definições e copie novamente o comando.

Ser-lhe-á pedido para iniciar sessão com `Connect-AzAccount`. Se a sua conta tiver acesso a vários tenants ou subscrições, o módulo pede-lhe que escolha.

A implementação apresenta então cada recurso à medida que é criado: o service principal, as tabelas personalizadas, as Data Collection Rules e as atribuições de função. Uma única execução normalmente demora alguns minutos.

{% hint style="info" %}
Quer ver primeiro o que aconteceria? Adicione `-WhatIf` a `Set-RJLogAnalyticsWorkspace` para uma pré-visualização What-If do Azure Resource Manager. Note que o início de sessão e a instalação dos `Az` módulos continuam a acontecer, porque a pré-visualização precisa de ambos.
{% endhint %}

{% hint style="info" %}
**Terminar sessão depois:** o início de sessão do Azure mantém-se ativo depois de o comando terminar. Quando acabar, execute `Disconnect-AzAccount` para terminar sessão da sessão existente.
{% endhint %}
{% endstep %}

{% step %}

#### Verifique no Portal

Regresse a **Definições → Log Analytics** e selecione **Atualizar**.

A página mostra agora a configuração da API Log Ingestion — subscrição, grupo de recursos, nome do workspace, ID do workspace do cliente e ID do tenant — como campos só de leitura, uma vez que estas definições passam a ser mantidas pelo módulo PowerShell. Em **Avançadas** pode rever os pontos finais, nomes de regras e nomes de streams das três Data Collection Rules.

Selecione **Verifique se existem problemas de configuração** para confirmar que todas as permissões Azure necessárias estão em vigor no workspace e em cada Data Collection Rule.
{% endstep %}

{% step %}

#### Confirme que os registos chegam

Abra [Registo de Auditoria](https://docs.realmjoin.com/pt/monitorizacao-e-registos/audit-log.md), os [Registos de Runbook](https://docs.realmjoin.com/pt/automatizacao/runbooks/runbook-logs.md) ou os registos operacionais e confirme que aparecem novas entradas. As entradas existentes de antes da migração também permanecem visíveis.

{% hint style="info" %}
A Azure precisa de alguns minutos para disponibilizar uma tabela personalizada recém-criada e a respetiva regra. Se nada chegar de imediato, espere um pouco e atualize.
{% endhint %}
{% endstep %}
{% endstepper %}

## Após a migração

### Mantenha por enquanto o registo de aplicação antigo

As entradas históricas em `AuditLogs_CL`, `OperationalLogs_CL` e `RunbookLogs_CL` ainda são lidas com o seu **registo de aplicação existente e segredo do cliente**. O Portal consulta as tabelas antigas e as novas em paralelo.

{% hint style="warning" %}
Não elimine o registo de aplicação e continue a renovar o seu segredo do cliente, enquanto ainda quiser ver dados de registo de antes da migração. Só a **chave partilhada do workspace** já não é necessária para o RealmJoin — deixou de ser usada para escrita.
{% endhint %}

Assim que os dados antigos tiverem expirado da sua [retenção do workspace](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/data-retention-archive?tabs=portal-1%2Cportal-2), pode remover o registo de aplicação.

### Manter o esquema atualizado

Se o RealmJoin alargar o esquema de registos numa futura versão, a página de definições mostra um aviso de que o esquema do Log Analytics implementado está desatualizado, juntamente com o comando para o atualizar. Esse é o **mesmo** `Set-RJLogAnalyticsWorkspace` comando — volte a executá-lo e as tabelas e regras são atualizadas no local.

## Solução de problemas

<details>

<summary>"O módulo RealmJoin está desatualizado - a execução não pode prosseguir"</summary>

Cada cmdlet verifica uma vez por sessão se está a executar a versão publicada mais recente do módulo. Instale a versão atual e depois feche a sessão e abra uma nova:

```powershell
Install-Module -Name RealmJoin -Force -Scope CurrentUser
```

</details>

<details>

<summary>É reportado um conflito de versões de módulo</summary>

Um `Az.*` módulo numa versão diferente daquela que o módulo RealmJoin fixa já está carregado na sessão. Isto não pode ser corrigido dentro da sessão em execução — feche o PowerShell, abra uma nova sessão e execute novamente o comando. Esta é também a razão para não usar o Azure Cloud Shell.

</details>

<details>

<summary>"É necessária aprovação de administrador" ou um erro de consentimento durante o início de sessão</summary>

O início de sessão usa a **Azure PowerShell** aplicação de primeira parte. Se o seu tenant restringir o consentimento do utilizador, um administrador tem de conceder uma vez o consentimento de administrador a essa aplicação.

</details>

<details>

<summary>A implementação falha ao criar atribuições de função</summary>

Criar as *Leitor do Log Analytics* e *Publicador de Métricas de Monitorização* atribuições requer uma função que possa gerir o acesso — por exemplo *Proprietário*, *Administrador de Acesso de Utilizador* ou *Administrador de Controlo de Acesso Baseado em Funções* no grupo de recursos ou na subscrição. *Contribuidor* sozinho não é suficiente.

As atribuições de função que já existam são detetadas e ignoradas, pelo que voltar a executar o comando após corrigir as permissões é seguro.

</details>

<details>

<summary>A implementação falha com um erro sobre a região do workspace</summary>

A implementação destina-se à região do grupo de recursos. Se o seu workspace existente estiver numa região diferente da do seu grupo de recursos, a Azure rejeita a alteração, porque a localização de um workspace existente não pode ser modificada. Nesse caso, contacte o suporte do RealmJoin.

</details>

<details>

<summary>O token já não é aceite</summary>

O token de integração no comando gerado é de curta duração (cerca de uma hora). Recarregue **Definições → Log Analytics** no Portal, copie novamente o comando e volte a executá-lo. A implementação Azure em si é idempotente, por isso uma segunda execução não causa qualquer dano.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-ingestion-api-migration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
