> 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/automatizacao/connecting-azure-automation/managed-app-migration.md).

# Mudança para a aplicação gerida do RealmJoin

Substitua o registo da aplicação RealmJoin Runbook Management por tenant e o respetivo segredo de cliente pela aplicação multi-tenant gerida do RealmJoin, usando o módulo RealmJoin PowerShell.

## Visão geral

Os tenants que se conectaram ao Azure Automation antes da integração baseada em PowerShell usam um **Gestão de Runbooks RealmJoin** registo de aplicação no seu próprio tenant. RealmJoin autentica-se no seu Automation Account com o ID de cliente e o segredo de cliente dessa aplicação.

Os tenants integrados recentemente já não fazem isto: RealmJoin usa a sua própria **aplicação multi-tenant**, à qual é atribuído Contributor na sua conta de Automação e nada mais. Pode mudar uma configuração existente com o [módulo PowerShell RealmJoin](/pt/implementacao/onboarding-realmjoin-portal/advanced-setup.md).

{% hint style="info" %}
É recomendável mudar para a app gerida. A configuração legada continua atualmente suportada; isso poderá mudar no futuro, e os clientes afetados serão informados separadamente.
{% endhint %}

### Por que mudar

* **Sem segredo de cliente para rodar.** O segredo por tenant expira e tem de ser renovado; quando expira, a sincronização e a execução dos runbooks param até alguém dar conta. A app gerida não tem segredo do seu lado.
* **Sem registo de aplicação para manter** no seu tenant.
* **Âmbito mais restrito.** O Service Principal legado recebia normalmente Contributor em todo o grupo de recursos. A app gerida recebe Contributor apenas na conta de Automação.
* A conta de Automação (nome e grupo de recursos), a respetiva identidade gerida atribuída pelo sistema com o seu ID de objeto, as funções do Entra ID e as permissões de aplicação atribuídas a essa identidade, e os runbooks importados são mantidos.

## O que a mudança altera

O mesmo `Set-RJAutomationAccount` é usado o mesmo comando que para uma nova configuração, direcionado para a sua **existente** conta de Automação. Ele:

* cria o **RealmJoin Azure Resources** Service Principal no seu tenant, se ainda não existir
* atribui-lhe **Contributor** nessa conta de Automação
* reafirma as permissões de aplicação da identidade gerida — Microsoft Graph, Exchange Online, Defender e SharePoint — para o conjunto que o módulo inclui
* indica ao RealmJoin para autenticar a partir de agora com a app gerida

A sua conta de Automação mantém o nome, a respetiva identidade gerida e o seu ID de objeto, pelo que as funções do Entra ID e quaisquer permissões que lhe atribuiu continuam válidas. Os runbooks não são reimportados do zero.

{% hint style="warning" %}
O registo reinicia a **ramo** do repositório partilhado de runbooks para `produção`. Se o seu tenant seguir deliberadamente um ramo diferente, configure-o novamente no Portal depois em Definições → Runbooks.
{% endhint %}

## Pré-requisitos

O mesmo que para uma nova configuração — veja [Pré-requisitos](/pt/automatizacao/connecting-azure-automation.md#prerequisites) na página de integração. Em resumo:

* Acesso à área de Definições no Portal RealmJoin, para obter o comando e o respetivo token
* PowerShell 5.1 ou posterior, numa sessão local recém-aberta — **não** Azure Cloud Shell
* Uma conta que possa criar Service Principals e conceder permissões de aplicação no Entra ID (*Administrador Global* ou *Administrador de Funções com Privilégios*) e que possa criar atribuições de funções na subscrição (*Proprietário*, ou *Contributor* mais *Administrador de Acesso do Utilizador*)

## Migração

{% stepper %}
{% step %}

#### Copie o comando do Portal RealmJoin

No Portal RealmJoin, vá para **Definições → Runbooks** (<https://portal.realmjoin.com/settings/runbooks-configuration>).

A página mostra o aviso **"Mudar para a app gerida RealmJoin"** juntamente com um bloco de comando pronto a copiar. Use o **Copiar** botão para o copiar.

<figure><img src="https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-84baa16d78a6621d669669725722fb774e6aa0ee%2Fmanaged-app-migration-notice.png?alt=media" alt="Settings → Runbooks with the notice &#x22;Switch to the RealmJoin managed app&#x22; and the pre-filled Set-RJAutomationAccount command"><figcaption><p>Aviso de migração e comando em Definições → Runbooks</p></figcaption></figure>

O comando está pré-preenchido com o seu grupo de recursos atual, nome da conta de Automação e subscrição:

```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-RJAutomationAccount -ResourceGroupName "<ResourceGroup>" -AutomationAccountName "<AutomationAccountName>" -SubscriptionId "<SubscriptionId>" -Token "<Token>" 6>&1
```

{% hint style="warning" %}
Certifique-se de que `-AutomationAccountName` está presente e indica o nome da sua **existente** conta. Sem isso, o módulo cria uma nova conta de Automação vazia em vez de mudar a que utiliza.
{% endhint %}
{% endstep %}

{% step %}

#### Execute o comando

Cole o bloco numa nova sessão do PowerShell e execute-o. O token é válido durante 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`. A implementação depois apresenta cada recurso e atribuição de função à medida que são aplicados; tudo o que já existe é detetado e ignorado.

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

{% step %}

#### Verifique no Portal

Volte para **Definições → Runbooks** e selecione **Atualizar**.

O aviso de migração desapareceu, e a página agora mostra **Definições de sincronização de Runbook** com as opções de ramo e de Hybrid Runbook Worker, além de uma **ligação ao Azure** secção apenas de leitura. O ID de cliente e o segredo de cliente já não fazem parte da configuração.

<figure><img src="https://686519968-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-06c1123395052f67c34b525ad9254d0cb2ca2990%2Fmanaged-app-migration-verified.png?alt=media" alt="Settings → Runbooks after the switch, with Runbook sync settings and the read-only Azure connection section"><figcaption><p>Configuração de runbooks após a mudança</p></figcaption></figure>

Verifique se o ramo é o que pretende e depois execute um runbook para confirmar que a execução continua a funcionar.
{% endstep %}

{% step %}

#### Limpar o antigo registo de aplicação

Quando tudo funcionar, o **Gestão de Runbooks RealmJoin** registo de aplicação já não é usado para runbooks e pode ser removido no Entra ID, juntamente com a sua atribuição da função Contributor no grupo de recursos.

{% hint style="warning" %}
Verifique primeiro o que mais usa esse registo de aplicação. É a mesma app que a configuração legada de [Log Analytics](/pt/monitorizacao-e-registos/log-analytics.md) pode reutilizar — se o seu tenant ainda usar a Data Collector API aí, ou ainda ler dados de registo escritos antes dessa migração, o registo de aplicação e o respetivo segredo continuam a ser necessários. Veja [Migração para a API de Ingestão de Logs](/pt/monitorizacao-e-registos/log-ingestion-api-migration.md).
{% endhint %}
{% endstep %}
{% endstepper %}

## Resolução de problemas

<details>

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

Cada cmdlet verifica uma vez por sessão se está a executar a versão publicada mais recente. Instale a versão atual e, em seguida, feche a sessão e abra uma nova:

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

</details>

<details>

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

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

</details>

<details>

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

Criar a atribuição de Contributor na conta de Automação requer uma função que possa gerir o acesso — por exemplo *Proprietário*, *Administrador de Acesso do Utilizador* ou *Administrador de Controlo de Acesso Baseado em Funções*. *Contributor* sozinho não é suficiente.

As atribuições de função que já existem são detetadas e ignoradas, por isso voltar a executar o comando depois de corrigir as permissões é seguro.

</details>

<details>

<summary>A implementação falha ao atribuir permissões de aplicação</summary>

Conceder funções de aplicação de Graph, Exchange, Defender e SharePoint à identidade gerida requer *Administrador Global* ou *Administrador de Funções com Privilégios*. Peça a alguém com essa função para executar o comando, ou volte a executá-lo você próprio depois de a função ser ativada.

</details>

<details>

<summary>A sincronização de runbooks deixa de funcionar após a mudança</summary>

Abra **Definições → Runbooks** e verifique o aviso mostrado no topo da página — RealmJoin verifica a configuração da conta de Automação sempre que a página é carregada. Em seguida, use **Mostrar cmdlet** em ligação ao Azure para voltar a executar o comando de configuração; é idempotente e volta a aplicar tudo o que estiver em falta.

</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/automatizacao/connecting-azure-automation/managed-app-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.