Tutorial: Gerir políticas avançadas de conectores de forma programática

Políticas avançadas de conectores (ACP) regulam o uso dos conectores com uma lista de permissões rigorosa que bloqueia os conectores por defeito. Para além da experiência no centro de administração do Power Platform , pode gerir o ACP com código usando a API do Power Platform e os SDKs de administração (Admin). Automatizar o ACP é útil quando se padroniza a governação em vários grupos de ambiente, se replica uma política base entre grupos ou se gerem políticas como parte de um pipeline de implementação.

Neste tutorial, saiba como:

  1. Autentique-se usando Power Platform API.
  2. Compreenda a forma da política ACP.
  3. Crie uma política e adicione-a a um grupo de ambiente.
  4. Ativa uma ação individual do conector.
  5. Aplicar ou atualizar uma política num único ambiente.
  6. Copiar uma política de um grupo de ambiente para outro.
  7. Remova o ACP de um grupo de ambientes.

Políticas avançadas de conectores são expostas através das governance/ruleBasedPolicies operações da API da Power Platform. Uma política contém um ou mais conjuntos de regras; o conjunto de regras com o ID ConnectorManagement contém a lista de permissões do conector ACP. Todos os exemplos no artigo utilizam a versão 2024-10-01API .

Pré-requisitos

Passo 1. Autenticar com a API do Power Platform

Todos os exemplos autenticam-se com o ID de cliente do registo da sua aplicação, seguindo as orientações em Autenticação. Os exemplos seguintes iniciam sessão de forma interativa como o utilizador atual. Para executar sem vigilância como principal de serviço, consulte o fluxo de cliente confidencial no artigo Autenticação e atribua ao principal de serviço um papel RBAC.

# Requires the MSAL.PS module: Install-Module MSAL.PS -Scope CurrentUser
Import-Module "MSAL.PS"

$clientId  = "<application (client) ID of your app registration>"
$apiBaseUrl = "https://api.powerplatform.com"
$apiVersion = "2024-10-01"

# Sign in interactively and request a token for the Power Platform API
$auth = Get-MsalToken -ClientId $clientId -Scope "https://api.powerplatform.com/.default" -Interactive
$headers = @{ Authorization = "Bearer $($auth.AccessToken)" }

Passo 2. Compreender a forma da política ACP

Uma política de conector avançada é uma política baseada em regras que contém um conjunto de regras com o ID ConnectorManagement. Esse conjunto de regras inclui um(a) version e os seus inputs contêm um(a) AllowedConnectorList, em que cada entrada permite um conector e define como as suas ações e tipos de ligação são regidos:

{
  "name": "Contoso ACP baseline",
  "ruleSets": [
    {
      "id": "ConnectorManagement",
      "version": "1.0",
      "inputs": {
        "AllowedConnectorList": [
          {
            "AllowedConnector": "/providers/Microsoft.PowerApps/apis/shared_office365",
            "AllowedActionsMode": "AllAllowed",
            "AllowedConnectionTypesMode": "AllAllowed"
          },
          {
            "AllowedConnector": "/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps",
            "AllowedActionsMode": "SomeAllowed",
            "AllowedActions": ["GetItem", "CreateRecord"],
            "AllowedConnectionTypesMode": "AllAllowed"
          }
        ]
      }
    }
  ]
}

Tenha em mente as seguintes questões semânticas:

  • Um conector que não está em AllowedConnectorList é bloqueado (default-deny).
  • Cada entrada define AllowedActionsMode. AllAllowed Permite todas as ações no conector. SomeAllowed restringe o conector às ações listadas no array AllowedActions da entrada. O Passo 4 mostra como adicionar uma ação e definir este modo.
  • AllowedConnectionTypesMode regula quais os tipos de ligação permitidos e segue o mesmo AllAllowed padrão.
  • Inclua o version do conjunto de regras ao criar ou atualizar uma política. Leia-a a partir de uma apólice existente e preserve o valor que o serviço devolve.

Tip

O valor exato de AllowedConnector é o identificador de recurso do conector. A forma mais fiável de aprender a forma dos conectores já existentes no seu tenant é ler primeiro uma política existente (o Passo 4 mostra como) ou usar o catálogo de conectores (descrito a seguir), e depois espelhar essa forma quando criar ou atualizar políticas.

Localize os IDs dos conectores e das ações com o catálogo de conectores

Para descobrir que conectores e ações pode permitir, use a API do Catálogo de Conectores. Lista os conectores disponíveis num ambiente, juntamente com os identificadores que coloca em AllowedConnector e AllowedActions.

Note

As operações do catálogo de conectores requerem um ID de ambiente no caminhoe um OData $filter que especifique o mesmo ambiente – por exemplo, $filter=environment eq '<environmentId>'. Ambos são obrigatórios.

$environmentId = "<environment ID>"
$filter = [uri]::EscapeDataString("environment eq '$environmentId'")

# List connectors available in the environment
$connectors = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/connectivity/environments/$environmentId/connectors?`$filter=$filter&api-version=$apiVersion" `
    -Headers $headers
$connectors.value | Select-Object name, @{ n = "displayName"; e = { $_.properties.displayName } }

# Get a single connector by ID (the connector's name, such as shared_office365)
$connectorId = "shared_office365"
$connector = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/connectivity/environments/$environmentId/connectors/$connectorId?`$filter=$filter&api-version=$apiVersion" `
    -Headers $headers
$connector.id   # full resource path to use as AllowedConnector

Utilize o id do conector (o caminho completo do recurso, como /providers/Microsoft.PowerApps/apis/shared_office365) como o valor de AllowedConnector e os IDs de operação do conector como os valores em AllowedActions. Pode aceder ao mesmo catálogo através do connectivity namespace dos SDKs de Administrador.

Passo 3. Crie uma política e adicione-a a um grupo de ambiente

Adicionar ACP a um grupo de ambiente é uma operação em duas partes: criar a política e depois atribuí-la ao grupo. A chamada create devolve a nova política id, que utiliza na chamada de atribuição.

Para atribuir a política ao grupo inteiro, envie um pedido de atribuição com um corpo vazio ({}). Todos os ambientes do grupo herdam a política e mantêm-se sincronizados com ela.

$environmentGroupId = "<environment group ID>"

# 1. Create the policy with a ConnectorManagement rule set
$policyBody = @{
    name     = "Contoso ACP baseline"
    ruleSets = @(
        @{
            id      = "ConnectorManagement"
            version = "1.0"
            inputs  = @{
                AllowedConnectorList = @(
                    @{
                        AllowedConnector           = "/providers/Microsoft.PowerApps/apis/shared_office365"
                        AllowedActionsMode         = "AllAllowed"
                        AllowedConnectionTypesMode = "AllAllowed"
                    }
                )
            }
        }
    )
} | ConvertTo-Json -Depth 10

$policy = Invoke-RestMethod -Method Post `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body $policyBody
Write-Host "Created policy $($policy.id)"

# 2. Assign the policy to the environment group (empty body = whole group)
Invoke-RestMethod -Method Post `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$($policy.id)/environmentGroups/$environmentGroupId/assignments?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body "{}"
Write-Host "Assigned policy $($policy.id) to group $environmentGroupId"

Passo 4: Ativar uma ação específica do conector

Para permitir apenas ações específicas num conector, defina o respetivo AllowedActionsMode como SomeAllowed e liste as ações permitidas em AllowedActions. Este exemplo adiciona uma ação, como uma ação oculta que não é selecionável no centro de administração, à lista de permissões de um conector e define o conector como SomeAllowed. Leia a política, atualize a entrada do conector e envie novamente o conjunto de regras atualizado utilizando patch. O patch atualiza um conjunto de regras por ID e mantém os outros conjuntos de regras da política intocados.

$policyId     = "<policy ID>"
$connectorId  = "shared_commondataserviceforapps"   # last segment of AllowedConnector
$actionToAdd  = "aibuilderpredict_customprompt"

# 1. Read the current policy
$policy = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId`?api-version=$apiVersion" `
    -Headers $headers

# 2. Find the ConnectorManagement rule set and the connector entry
$ruleSet = $policy.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" }
$entry = $ruleSet.inputs.AllowedConnectorList |
    Where-Object { ($_.AllowedConnector -split "/")[-1] -eq $connectorId }

# 3. Restrict the connector to specific actions: add the action and set SomeAllowed
if ($entry) {
    $actions = @()
    if ($entry.PSObject.Properties.Name -contains "AllowedActions") { $actions = @($entry.AllowedActions) }
    if ($actions -notcontains $actionToAdd) { $actions += $actionToAdd }
    $entry | Add-Member -NotePropertyName AllowedActions -NotePropertyValue $actions -Force
    $entry.AllowedActionsMode = "SomeAllowed"

    # 4. Patch only the modified rule set back to the policy
    $patchBody = @{ name = $policy.name; ruleSets = @($ruleSet) } | ConvertTo-Json -Depth 10
    Invoke-RestMethod -Method Patch `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId`?api-version=$apiVersion" `
        -Headers $headers -ContentType "application/json" -Body $patchBody
    Write-Host "Set '$connectorId' to SomeAllowed with '$actionToAdd' in policy $policyId"
}

Passo 5. Aplicar ou atualizar uma política num único ambiente

Pode direcionar uma política para um único ambiente em vez de um grupo ambiental. Esta abordagem é útil para ambientes de alto risco, piloto ou regulados. Atribui a política ao ambiente e usa o mesmo padrão de patch do Passo 4 para a modificar mais tarde. Cada ambiente apoia uma política ACP eficaz.

$policyId       = "<policy ID>"
$environmentId  = "<environment ID>"

# Assign the policy directly to the environment
Invoke-RestMethod -Method Post `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId/environments/$environmentId/assignments?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body "{}"
Write-Host "Assigned policy $policyId to environment $environmentId"

Passo 6. Copiar uma política de um grupo de ambiente para outro

Ao replicar uma linha de base de governação para outro grupo, escolha quanto pretende copiar utilizando a opção CopyAllRules:

  • CopyAllRules = true: Criar uma nova política a partir de todos os conjuntos de regras do grupo de origem e atribuí-la ao grupo-alvo. A governação do grupo-alvo torna-se uma cópia independente da fonte.
  • CopyAllRules = false: Extrair apenas o ConnectorManagement conjunto de regras da política de origem e fundi-lo na política existente do grupo-alvo. A operação de patch adiciona ou atualiza o conjunto de regras por ID, para que o grupo-alvo mantenha as suas outras regras.
$sourceGroupId = "<source environment group ID>"
$targetGroupId = "<target environment group ID>"
$CopyAllRules  = $true

# 1. Find and read the policy assigned to the source group
$sourceAssignments = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/environmentGroups/$sourceGroupId/assignments?api-version=$apiVersion" `
    -Headers $headers
$sourcePolicyId = $sourceAssignments.value[0].policyId
$source = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$sourcePolicyId`?api-version=$apiVersion" `
    -Headers $headers

if ($CopyAllRules) {
    # 2a. Copy ALL rule sets into a new policy and assign it to the target group
    $copyBody = @{ name = "$($source.name) (copy)"; ruleSets = $source.ruleSets } | ConvertTo-Json -Depth 20
    $copy = Invoke-RestMethod -Method Post `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies?api-version=$apiVersion" `
        -Headers $headers -ContentType "application/json" -Body $copyBody
    Invoke-RestMethod -Method Post `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$($copy.id)/environmentGroups/$targetGroupId/assignments?api-version=$apiVersion" `
        -Headers $headers -ContentType "application/json" -Body "{}"
    Write-Host "Copied all rules to policy $($copy.id) and assigned it to group $targetGroupId"
}
else {
    # 2b. Merge ONLY the ConnectorManagement rule into the target group's existing policy
    $sourceCm = $source.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" }

    $targetAssignments = Invoke-RestMethod -Method Get `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/environmentGroups/$targetGroupId/assignments?api-version=$apiVersion" `
        -Headers $headers
    $targetPolicyId = $targetAssignments.value[0].policyId
    $targetPolicy = Invoke-RestMethod -Method Get `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$targetPolicyId`?api-version=$apiVersion" `
        -Headers $headers

    # Patch adds or updates the ConnectorManagement rule set by ID, keeping the target's other rules
    $patchBody = @{ name = $targetPolicy.name; ruleSets = @($sourceCm) } | ConvertTo-Json -Depth 20
    Invoke-RestMethod -Method Patch `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$targetPolicyId`?api-version=$apiVersion" `
        -Headers $headers -ContentType "application/json" -Body $patchBody
    Write-Host "Merged the ConnectorManagement rule into target policy $targetPolicyId"
}

Passo 7. Remover o ACP de um grupo de ambiente

Embora um grupo tenha uma regra ACP ativa, todos os ambientes do grupo correspondem à política do grupo. A forma de remover a imposição depende de querer que esses ambientes mantenham a configuração atual ou limpem completamente o ACP:

  • Remover a regra da política do grupo para impedir que o grupo gere o ACP. Use a removeRule operação para remover o conjunto de ConnectorManagement regras da política do grupo. Os ambientes mantêm a configuração ACP aplicada pela última vez, mas já não estão sincronizados com o grupo. Podes gerir cada ambiente individualmente e deixá-los divergir.
  • Remover o ACP do grupo e de todos os ambientes para desligar o ACP em todo o lado. Remova a regra da política do grupo e, em seguida, percorra todos os ambientes do grupo e remova igualmente o conjunto de regras ConnectorManagement da política de cada ambiente.

Note

Remover a regra da política de um grupo não elimina automaticamente o ACP dos ambientes que a herdaram. Esses ambientes mantêm a última configuração que lhes foi aplicada para evitar uma lacuna na imposição. Para limpar o ACP em todo o lado, remove-o de cada ambiente, como mostrado no exemplo do ciclo. Para mais informações, consulte Políticas Avançadas de Conectores.

Remover a regra da política do grupo

O exemplo seguinte remove o ConnectorManagement conjunto de regras de uma política usando a removeRule operação.

$policyId = "<policy ID>"

# Read the policy, then send the rule set to remove
$policy = Invoke-RestMethod -Method Get `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId`?api-version=$apiVersion" `
    -Headers $headers
$ruleSet = $policy.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" }

$body = @{ name = $policy.name; ruleSets = @($ruleSet) } | ConvertTo-Json -Depth 10
Invoke-RestMethod -Method Patch `
    -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$policyId/removeRule?api-version=$apiVersion" `
    -Headers $headers -ContentType "application/json" -Body $body
Write-Host "Removed the ConnectorManagement rule set from policy $policyId"

Remover o ACP de todos os ambientes do grupo

Para desligar o ACP em todos os ambientes de um grupo, primeiro remova a regra da política do grupo (exemplo anterior), depois repita a remoção para a própria política de cada ambiente. Leia a política atribuída a cada ambiente a partir da sua atribuição de ambiente e depois recorra removeRule a essa política. Forneça os IDs de ambiente que pertencem ao grupo, ou enumere-os utilizando as APIs de gestão do ambiente.

# Environment IDs that belong to the group
$environmentIds = @("<environment ID 1>", "<environment ID 2>")

foreach ($environmentId in $environmentIds) {
    # Find the policy currently assigned to the environment
    $envAssignments = Invoke-RestMethod -Method Get `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/environments/$environmentId/assignments?api-version=$apiVersion" `
        -Headers $headers
    if (-not $envAssignments.value) { continue }
    $envPolicyId = $envAssignments.value[0].policyId

    # Remove the ConnectorManagement rule set from that environment's policy
    $envPolicy = Invoke-RestMethod -Method Get `
        -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$envPolicyId`?api-version=$apiVersion" `
        -Headers $headers
    $ruleSet = $envPolicy.ruleSets | Where-Object { $_.id -eq "ConnectorManagement" }
    if ($ruleSet) {
        $body = @{ name = $envPolicy.name; ruleSets = @($ruleSet) } | ConvertTo-Json -Depth 10
        Invoke-RestMethod -Method Patch `
            -Uri "$apiBaseUrl/governance/ruleBasedPolicies/$envPolicyId/removeRule?api-version=$apiVersion" `
            -Headers $headers -ContentType "application/json" -Body $body
        Write-Host "Removed ACP from environment $environmentId"
    }
}

A mesma chamada por ambiente removeRule funciona com os SDKs C# e Python mostrados anteriormente. Envolva a chamada num ciclo sobre os IDs de ambiente do grupo.

Conteúdo relacionado

Políticas avançadas de conectores
Políticas Baseadas em Regras - Referência da API REST
Authentication
Tutorial: Atribuir papéis aos principais de serviço
Visão geral sobre programabilidade e extensibilidade

  • Last updated on