Recursos com nomes exclusivos
Este artigo compara estratégias de chave exclusivas de recursos em APIs do Microsoft Azure e APIs do Microsoft Graph e as alterações feitas nas APIs do Microsoft Graph para permitir que elas sejam usadas na infraestrutura declarativa como arquivos de modelo de código, como arquivos Bicep. Ele também explica como essas alterações podem ser usadas para fazer referência a recursos existentes do Microsoft Graph criados por meio de mecanismos diferentes da implantação do arquivo Bicep.
Importante
O Microsoft Graph Bicep está atualmente em pré-visualização. Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.
Chaves de recursos do Azure e do Microsoft Graph
As APIs do Microsoft Azure e do Microsoft Graph usam mecanismos sutilmente diferentes para criar recursos. Essas diferenças tornam-se mais aparentes ao tentar declarar ambos os recursos nos mesmos arquivos de modelo do Bicep.
O padrão padrão da API do Microsoft Azure para criar recursos é usar o método HTTP PUT com uma chave exclusiva fornecida pelo cliente chamada name. Esta operação idempotente cria o recurso com o valor fornecido name , se ele não existir, ou atualiza (substitui) se ele existe:
PUT /resourceCollection/{nameValue}
O padrão padrão da API do Microsoft Graph para criar recursos é usar o método HTTP POST. Esse método não é idempotente e retorna uma chave de ID exclusiva gerada pelo serviço chamada id.
POST /resourceCollection
As atualizações dos recursos existentes são realizadas usando o método HTTP PATCH, que, ao contrário do PUT, não usa uma semântica de substituição.
A semântica de criação do Microsoft Graph atende bem à maioria dos desenvolvedores, mas não atende a dois requisitos principais para modelos de arquivo declarativo:
- Repetibilidade: uma implantação de arquivo de modelo deve ser executada várias vezes com o mesmo resultado, que o ambiente de implantação corresponda aos recursos declarados no arquivo de modelo. Essa repetibilidade não é possível para métodos não idempotentes como o POST.
- Chaves ou nomes fornecidos pelo cliente: a criação e manutenção de um arquivo de modelo declarativo requer a declaração antecipada de nomes de recursos (ou chaves fornecidas pelo cliente). Para a maioria das APIs do Microsoft Graph, as chaves fornecidas pelo cliente não são possíveis.
Chaves fornecidas pelo cliente Microsoft Graph
Alguns recursos do Microsoft Graph suportam uma propriedade de chave fornecida pelo cliente, permitindo que um mecanismo idempotente "upsert" crie o recurso se ele não existir ou atualize-o se existir. Essa propriedade de chave fornecida pelo cliente é mais provável que seja uma chave alternativa, mas às vezes é a chave primária.
PATCH /resourceCollection(clientProvidedAlternateKeyProperty='nameValue')
Quando o recurso é criado usando uma chave alternativa, um valor gerado por serviço é definido para a propriedade de chave primária.
Somente recursos que seguem esse padrão são expostos como tipos do Microsoft Graph Bicep, com poucas exceções.
A tabela a seguir lista as propriedades de chave fornecidas pelo cliente para recursos do Microsoft Graph suportados em arquivos Bicep:
| Recurso do Microsoft Graph | Propriedade de chave fornecida pelo cliente |
|---|---|
| Aplicações | uniqueName |
| Credenciais de identidade federada | Designação |
| Função do aplicativo atribuída a | Implícito a partir dos valores de propriedade que identificam exclusivamente o objeto |
| Grupos | uniqueName |
| Concessões de permissão OAuth2 | Implícito a partir dos valores de propriedade que identificam exclusivamente o objeto |
| Principais de serviço | appId |
Recursos existentes do Microsoft Graph
Você pode fazer referência a recursos existentes do Microsoft Graph em modelos Bicep pela propriedade de chave fornecida pelo cliente suportada. Os recursos criados via HTTP POST podem não ter essa propriedade definida e exigir um backfill único.
Uma vez definida, a propriedade de chave fornecida pelo cliente permite que o recurso seja declarado em um arquivo Bicep para reimplantação. Para ler as propriedades do recurso sem reimplantar, use a palavra-chave existente .
Importante
A propriedade de chave fornecida pelo cliente não pode ser alterada uma vez definida.