FAQ sobre erros de CLI para desenvolvedores Azure

Este artigo apresenta soluções para erros comuns que pode encontrar ao usar a CLI do Azure Developer (azd).

Autorização falhada para escrita de atribuição de funções

Mensagem de erro:The template deployment failed with error: 'Authorization failed for template resource '<guid>' of type 'Microsoft.Authorization/roleAssignments'. The client '##Email##' with object id '<guid>' does not have permission to perform action 'Microsoft.Authorization/roleAssignments/write' at scope '<resourceId>'.'

Cause: Não tem permissões suficientes para atribuir funções na subscrição ou grupo de recursos de Azure alvo. Isto é comum quando a tua conta de utilizador tem Contributor acesso mas não tem acesso a Owner nem a User Access Administrator. Contributor Permite criar recursos mas não conceder permissões (atribuir papéis) a esses recursos.

Resolução: Garante que a tua conta tem a função Proprietário ou Administrador de Acesso ao Utilizador na subscrição ou grupo de recursos onde estás a implementar. Se não conseguires obter estas funções, pede a um administrador que realize a implantação inicial ou as atribuições de funções por ti. Para obter mais informações, consulte Funções predefinidas do Azure.

A atribuição de função já existe

Mensagem de erro:The role assignment already exists.

Causa: Este erro ocorre quando a implementação tenta criar uma atribuição de função que já existe no recurso. Embora as implementações do Azure Resource Manager (ARM) sejam idempotentes, certas configurações ou condições de corrida nos modelos podem desencadear este erro durante a reimplantação.

Resolução: Este erro é frequentemente intermitente ou benigno.

1. Tente novamente a implementação: Execute azd up ou azd deploy novamente.
2. Check Bicep templates: Se mantiver o template, assegure que as atribuições de papéis utilizam propriedades válidas name (frequentemente GUIDs estritamente determinísticos) para garantir a idempotência. Use a função guid() Bicep para gerar nomes determinísticos.

ID de arrendatário, ID principal ou âmbito não pode ser atualizado

Mensagem de erro:Tenant ID, application ID, principal ID, and scope are not allowed to be updated.

Causa: Estás a tentar redistribuir uma atribuição de função com propriedades que diferem da atribuição existente. As atribuições de funções são imutáveis; não podes alterar o principal ID (o utilizador/app que recebe a função) nem o âmbito de um ID de atribuição existente.

Resolution:

1. Verificar parâmetros: Certifique-se de que não está a passar acidentalmente um ID de principal diferente (por exemplo, alternar entre um utilizador e um principal de serviço) para o mesmo recurso de atribuição de funções.
2. Clean up: Se precisares de alterar a atribuição, elimina manualmente a atribuição de funções em conflito no portal Azure ou via CLI usando az role assignment delete, de seguida, volta a implementar.

Capacidade regional ou SKU indisponível

Mensagem de erro:The region 'eastus2' currently does not have enough resources available to provision services with the SKU 'standard'. (ou 'básico')

Causa: A região de Azure selecionada está temporariamente fora de capacidade para o SKU de serviço solicitado. Isto é atualmente comum em serviços de IA (como Azure OpenAI) em regiões populares como eastus2.

Resolution:

1. Mudança de localização: Execute azd env set AZURE_LOCATION <new-region> para mudar para uma região com melhor disponibilidade (por exemplo, swedencentral, westus3, francecentral).
2. Verificar disponibilidade: Use a página Azure Produtos por Região ou execute az account list-locations para verificar as regiões onde o serviço e o SKU estão disponíveis.

Quota de TPM excedida para modelos de IA

Mensagem de erro:This operation require <amount> new capacity in quota Tokens Per Minute (thousands) - <model> - GlobalStandard, which is bigger than the current available capacity <available>.

Causa: A sua subscrição atingiu o limite de quota para Tokens Por Minuto (TPM) para o modelo OpenAI Azure especificado na região-alvo.

Resolution:

1. Solicitar Quota: Solicitar aumento de quota através do Azure AI Studio ou portal Azure. Para mais informações, consulte Gerir Azure OpenAI Service quota.
2. Mudança de Modelo/Região: Muda para uma região onde tenhas quotas não usadas ou usa uma versão diferente que se encaixe nos teus limites.

If-Match precondição falhou

Mensagem de erro:The specified precondition 'If-Match = ""<guid>""' failed.

Causa: Esta questão indica tipicamente um conflito de concorrência. Dois processos podem estar a tentar atualizar o mesmo recurso simultaneamente, ou o seu estado local está fora de sincronia com o recurso na cloud (ETag obsoleto).

Resolução: Tente novamente a operação. Se o erro persistir:

1. Garanta que nenhuma outra implementação (pipelines CI/CD, outros colegas) esteja a direcionar-se para o mesmo ambiente simultaneamente.
2. Se estiver a usar Bicep, verifique se o seu modelo define corretamente as dependências (dependsOn) para evitar modificações paralelas no mesmo recurso.

Conta de Serviços Cognitivos em estado Aceito

Mensagem de erro:Call to Microsoft.CognitiveServices/accounts failed. Error message: Account <resourceId> in state Accepted.

Cause: Este erro é uma questão de timing em que um recurso dependente tenta interagir com a conta de Serviços Cognitivos (IA Azure) antes de esta estar totalmente provisionada e ativa. Também podes adicionar um gancho de comando (por exemplo, postprovision) no teu azure.yaml para pausar ou verificar a prontidão dos recursos antes de prosseguir.

Provisão de revisão da aplicação de container expirada

Mensagem de erro:Failed to provision revision for container app <appName>. Error details: Operation expired.

Cause: A aplicação Azure Container falhou em iniciar no período de tempo predefinido. Motivos comuns:

• A imagem do contentor é demasiado grande e demora demasiado tempo a puxar.
• A aplicação crasha ao arrancar.
• A aplicação demora demasiado tempo a ouvir na porta configurada.

Resolution:

1. Verifique Logs: Veja os registos do contentor no portal Azure (Log Stream) ou usando azd monitor para ver se a aplicação está a crashar.
2. Revisão da Configuração: Garante que a targetPort na tua configuração corresponde à porta através da qual a tua aplicação escuta. Para mais passos de resolução de problemas, veja Resolução de problemas Azure Container Apps
3. Verifique Logs: Veja os registos do contentor no portal Azure (Log Stream) ou usando azd monitor para ver se a aplicação está a crashar.
4. Revisão da Configuração: Assegura que a targetPort na tua configuração corresponde à porta onde a tua app escuta.
5. Otimizar a Imagem: Reduza o tamanho da imagem do seu container para acelerar o pull.