Recursos con nombre único
En este artículo se comparan las estrategias clave únicas de recursos en las API de Microsoft Azure y las API de Microsoft Graph y los cambios realizados en las API de Microsoft Graph para permitir que se usen en la infraestructura declarativa como archivos de plantilla de código, como archivos de Bicep. También se explica cómo se pueden usar estos cambios para hacer referencia a los recursos existentes de Microsoft Graph creados a través de mecanismos distintos de la implementación de archivos de Bicep.
Importante
Microsoft Graph Bicep está actualmente en versión preliminar. Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.
Claves de recursos de Azure y Microsoft Graph
Las API de Microsoft Azure y Microsoft Graph usan mecanismos subdirecursos para crear recursos. Estas diferencias se vuelven más evidentes al intentar declarar ambos recursos en los mismos archivos de plantilla de Bicep.
El patrón estándar de la API de Microsoft Azure para crear recursos es usar el método HTTP PUT con una clave única proporcionada por el cliente denominada name. Esta operación idempotent crea el recurso con el valor proporcionado name si no existe o actualiza (reemplazar) si existe:
PUT /resourceCollection/{nameValue}
El patrón estándar de Microsoft Graph API para crear recursos es usar el método HTTP POST. Este método no es idempotente y devuelve una clave de identificador único generada por el servicio denominada id.
POST /resourceCollection
Las actualizaciones de los recursos existentes se realizan mediante el método HTTP PATCH, que a diferencia de PUT no usa una semántica de reemplazo.
La semántica de creación de Microsoft Graph sirve bien a la mayoría de los desarrolladores, pero no cumple dos requisitos clave para las plantillas de archivo declarativas:
- Repetibilidad: una implementación de archivos de plantilla debe ejecutarse varias veces con el mismo resultado, que el entorno de implementación coincide con los recursos declarados en el archivo de plantilla. Esta repetibilidad no es posible para métodos nonidempotentes como POST.
- Claves o nombres proporcionados por el cliente: la creación y el mantenimiento de un archivo de plantilla declarativo requiere declarar nombres de recursos (o claves proporcionadas por el cliente) por adelantado. Para la mayoría de las API de Microsoft Graph, las claves proporcionadas por el cliente no son posibles.
Claves proporcionadas por el cliente de Microsoft Graph
Algunos recursos de Microsoft Graph admiten una propiedad de clave proporcionada por el cliente, lo que permite un mecanismo "upsert" idempotent para crear el recurso si no existe o actualizarlo si lo hace. Esta propiedad de clave proporcionada por el cliente es más probable que sea una clave alternativa, pero a veces es la clave principal.
PATCH /resourceCollection(clientProvidedAlternateKeyProperty='nameValue')
Cuando el recurso se crea mediante una clave alternativa, se establece un valor generado por el servicio para la propiedad de clave principal.
Solo los recursos que siguen este patrón se exponen como tipos de Bicep de Microsoft Graph, con pocas excepciones.
En la tabla siguiente se enumeran las propiedades clave proporcionadas por el cliente para los recursos de Microsoft Graph admitidos en los archivos de Bicep:
| Recurso de Microsoft Graph | Propiedad de clave proporcionada por el cliente |
|---|---|
| APLICACIONES | uniqueName |
| Credenciales de identidad federada | name |
| Rol de aplicación asignado a | Implícito en los valores de propiedad que identifican de forma única el objeto |
| Grupos | uniqueName |
| Concesiones de permisos de OAuth2 | Implícito en los valores de propiedad que identifican de forma única el objeto |
| Entidades de servicio | appId |
Recursos existentes de Microsoft Graph
Puede hacer referencia a los recursos existentes de Microsoft Graph en plantillas de Bicep mediante la propiedad de clave proporcionada por el cliente compatible. Es posible que los recursos creados a través de HTTP POST no tengan este conjunto de propiedades y requieran un reposición de un solo uso.
Una vez establecida, la propiedad de clave proporcionada por el cliente permite declarar el recurso en un archivo de Bicep para la reimplementación. Para leer las propiedades del recurso sin volver a implementar, use la palabra clave existente .
Importante
La propiedad de clave proporcionada por el cliente no se puede cambiar una vez establecida.