Recursos com nomes exclusivos
Este artigo compara as principais estratégias exclusivas de recursos nas APIs do Microsoft Azure e nas 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 de arquivo Bicep.
Importante
O Microsoft Graph Bicep está atualmente em versão prévia. Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.
Chaves de recurso 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 se tornam mais aparentes ao tentar declarar esses dois 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. Essa 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 nos recursos existentes são realizadas usando o método HTTP PATCH, que, ao contrário de 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 declarativos:
- 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 a manutenção de um arquivo de modelo declarativo exigem 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 do Microsoft Graph
Alguns recursos do Microsoft Graph dão suporte a 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 provavelmente 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 pelo serviço é definido para a propriedade da chave primária.
Somente os recursos que seguem esse padrão são expostos como tipos Bicep do Microsoft Graph, com poucas exceções.
A tabela a seguir lista as propriedades de chave fornecidas pelo cliente para recursos do Microsoft Graph com suporte em arquivos Bicep:
| Recurso do Microsoft Graph | Propriedade de chave fornecida pelo cliente |
|---|---|
| Aplicativos | nome único |
| Credenciais de identidade federada | name |
| Função de aplicativo atribuída a | Implícito nos valores de propriedade que identificam exclusivamente o objeto |
| Grupos | nome único |
| Concessões de permissão OAuth2 | Implícito nos valores de propriedade que identificam exclusivamente o objeto |
| Entidades 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 com suporte. Os recursos criados por meio de HTTP POST podem não ter essa propriedade definida e exigir um aterramento único.
Depois de 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 depois de definida.