MS Graph API: Filter queries

In response to my blog post about querying groups & planners via the MS Graph API, a friend asked me how to query members of a group without knowing the group ID but just the group name. Let's find out how filters in the MS Graph API work.

Assuming we have the following code to query all groups via the MS Graph API SDK for PHP:

use Microsoft\Graph\Generated\Groups\GroupsRequestBuilderGetRequestConfiguration;
use Microsoft\Graph\Generated\Models\Group;
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Kiota\Authentication\Oauth\ClientCredentialContext;

$tenantId = '';
$clientId = '';
$clientSecret = '';

$tokenRequestContext = new ClientCredentialContext($tenantId, $clientId, $clientSecret);
$graphServiceClient = new GraphServiceClient($tokenRequestContext);

$groupsRequestConfig = new GroupsRequestBuilderGetRequestConfiguration();
$groupsRequestConfig->queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters();

try {
    $groups = $graphServiceClient->groups()->get($groupsRequestConfig)->wait();
    foreach ($groups->getValue() as $group) {
        /** var Group $group */
    }
} catch (Exception $e) {
    echo $e->getMessage();
}

The Microsoft Graph API supports the so-called $filter OData query parameter. Passing that parameter alongside the request allows us to retrieve a subset of a specific collection matching the provided filter rules.

The filter expression supports equality operators (eq, ne, not, in, has), relational operators (lt, gt, le, ge), conditional operators (end, or), and even functions (startswith, endswith, contains). This allows you to build complex search requests to filter whatever data you need.

How does it look in the code? The filter query needs to be passed to the GroupsRequestBuilderGetRequestConfiguration::createQueryParameters() method call as 3rd parameter like this:

$filter = "displayName eq 'MyGroup'";

$groupsRequestConfig = new GroupsRequestBuilderGetRequestConfiguration();
$groupsRequestConfig->queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters(null, null, $filter);

This request will return the group with the displayName set to "MyGroup". If you want to return all groups that start with the term "My", you can use the startswith() function like this:

$filter = "startswith(displayName, 'My')";

$groupsRequestConfig = new GroupsRequestBuilderGetRequestConfiguration();
$groupsRequestConfig->queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters(null, null, $filter);

For an overview which properties you can filter and which filter mechanisms will work for the different properties, head over here where Microsoft has covered the different search capabilities.

Besides the $filter search parameter, an additional $search parameter supports more complex search requests. However, the docs state that "The $search query parameter is currently not available in Azure AD B2C tenants." which may be the reason that I could not get it to work.