Modeling relationships in Microsoft Graph Bicep types

Microsoft Graph APIs has two distinct relationship models:

1. Relationships between entity types: For this relationship type, the API provides a "link" between two different types. The canonical example is a group and its members. You can manage memberships by adding and removing members (existing users, service principals, devices, and groups) to and from the group. For a group containing user members, deleting the group does not delete the users that are members of the group, as groups and users have an independent lifecycle.
2. Parent-child relationships: For this relationship type, child resources are "contained" within the parent resource and the life-cycle of the child resource is tied to the parent. For example, federatedIdentityCredentials is a child collection of an application instance. If the application is deleted, the application's federatedIdentityCredentials is also deleted.

In this article, we delve into how both of these relationship types are exposed in Microsoft Graph Bicep types and any extra functionality that the Microsoft Graph Bicep extension provides.

Relationships between entity types

Note

Unless explicitly mentioned, the relationship modeling experiences described in this section requires the use of Microsoft Graph Bicep types version v0.2.0-preview or later.

These relationships are modeled using the MicrosoftGraphRelationship type. The example shows the modeling for a group's members and owners properties (other required group properties aren't shown for brevity). The relationships array property contains a list of canonical IDs (primary key ID) to other Microsoft Graph resources.

resource group 'Microsoft.Graph/groups@v1.0' = {
  members: {
    relationships: [id1, id2, id3]
  }
  owners: {
    relationships: [id4, id5]
  }
}

Controlling relationship behavior

By default, all relationship updates use append semantics. Append adds a relationship for each ID in the list if the relationship isn't already in place. This mirrors the underlying default behavior of Microsoft Graph API. Alternatively, you can set a relationship update to use replace semantics. Replace semantics completely replaces whatever exists in the service with the relationships specified in the Bicep template. In the example, the group's existing members are replaced with id1, id2, and id3:

resource group 'Microsoft.Graph/groups@v1.0' = {
  members: {
    relationshipSemantics: 'replace'
    relationships: [id1, id2, id3]
  }
  owners: {
    relationships: [id4, id5]
  }
}

The relationship behavior can also be set at the template level in the extension statement:

extension graphV1 with {
  relationshipSemantics: 'replace'
}

This sets all relationships in the Bicep template to use replace semantics. This global behavior can be overridden in each relationship declaration.

Microsoft Graph Bicep extension functionality

With the v0.2.0-preview, the Microsoft Graph Bicep extension orchestrates the replace semantics logic, figuring out which members to add and remove from the relationship. Additionally, the Microsoft Graph Bicep extension orchestrates batching relationship requests to overcome Microsoft Graph API request limits for both reads and writes.

Parent-child relationships

In Bicep, parent-child relationships can be declared in different ways in template files. The most common way of declaring parent-child is by nesting a child resource under the parent resource. A good example of a nested child is federated identity credentials.