Package 'AzureGraph'

Title: Simple Interface to 'Microsoft Graph'
Description: A simple interface to the 'Microsoft Graph' API <https://learn.microsoft.com/en-us/graph/overview>. 'Graph' is a comprehensive framework for accessing data in various online Microsoft services. This package was originally intended to provide an R interface only to the 'Azure Active Directory' part, with a view to supporting interoperability of R and 'Azure': users, groups, registered apps and service principals. However it has since been expanded into a more general tool for interacting with Graph. Part of the 'AzureR' family of packages.
Authors: Hong Ooi [aut, cre], Microsoft [cph]
Maintainer: Hong Ooi <hongooi73@gmail.com>
License: MIT + file LICENSE
Version: 1.3.4
Built: 2024-02-03 04:39:57 UTC
Source: https://github.com/azure/azuregraph

Help Index


Registered app in Azure Active Directory

Description

Base class representing an AAD app.

Format

An R6 object of class az_app, inheriting from az_object.

Fields

Methods

Initialization

Creating new objects of this class should be done via the create_app and get_app methods of the ms_graph class. Calling the new() method for this class only constructs the R object; it does not call the Microsoft Graph API to create the actual app.

Microsoft Graph overview, REST API reference

List methods

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=Inf. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

See Also

ms_graph, az_service_principal, az_user, az_group, az_object

Examples

## Not run: 

gr <- get_graph_login()
app <- gr$create_app("MyNewApp")

# password resetting: remove the old password, add a new one
pwd_id <- app$properties$passwordCredentials[[1]]$keyId
app$add_password()
app$remove_password(pwd_id)

# set a redirect URI
app$update(publicClient=list(redirectUris=I("http://localhost:1410")))

# add API permission (access Azure Storage as user)
app$update(requiredResourceAccess=list(
    list(
        resourceAppId="e406a681-f3d4-42a8-90b6-c2b029497af1",
        resourceAccess=list(
            list(
                id="03e0da56-190b-40ad-a80c-ea378c433f7f",
                type="Scope"
            )
        )
    )
))

# add a certificate from a .pem file
app$add_certificate("cert.pem")

# can also read the file into an openssl object, and then add the cert
cert <- openssl::read_cert("cert.pem")
app$add_certificate(cert)

# add a certificate stored in Azure Key Vault
vault <- AzureKeyVault::key_vault("mytenant")
cert2 <- vault$certificates$get("certname")
app$add_certificate(cert2)

# change the app name
app$update(displayName="MyRenamedApp")


## End(Not run)

Device in Azure Active Directory

Description

Class representing a registered device.

Format

An R6 object of class az_device, inheriting from az_object.

Fields

Methods

Initialization

Create objects of this class via the list_registered_devices() and list_owned_devices() methods of the az_user class.

See Also

ms_graph, az_user, az_object

Microsoft Graph overview, REST API reference


Directory role

Description

Class representing a role in Azure Active Directory.

Format

An R6 object of class az_directory_role, inheriting from az_object.

Fields

Methods

Initialization

Currently support for directory roles is limited. Objects of this class should not be initialized directly.

List methods

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=Inf. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

See Also

ms_graph, az_user

Microsoft Graph overview, REST API reference


Group in Azure Active Directory

Description

Class representing an AAD group.

Format

An R6 object of class az_group, inheriting from az_object.

Fields

Methods

Initialization

Creating new objects of this class should be done via the create_group and get_group methods of the ms_graph and az_app classes. Calling the new() method for this class only constructs the R object; it does not call the Microsoft Graph API to create the actual group.

List methods

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=Inf. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

See Also

ms_graph, az_app, az_user, az_object

Microsoft Graph overview, REST API reference

Examples

## Not run: 

gr <- get_graph_login()
usr <- gr$get_user("myname@aadtenant.com")

grps <- usr$list_group_memberships()
grp <- gr$get_group(grps[1])

grp$list_members()
grp$list_owners()

# capping the number of results
grp$list_members(n=10)

# get the pager object for a listing method
pager <- grp$list_members(n=NULL)
pager$value


## End(Not run)

Azure Active Directory object

Description

Base class representing an Azure Active Directory object in Microsoft Graph.

Format

An R6 object of class az_object, inheriting from ms_object.

Fields

Methods

Initialization

Objects of this class should not be created directly. Instead, create an object of the appropriate subclass: az_app, az_service_principal, az_user, az_group.

List methods

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=Inf. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

See Also

ms_graph, az_app, az_service_principal, az_user, az_group

Microsoft Graph overview, REST API reference


Service principal in Azure Active Directory

Description

Class representing an AAD service principal.

Format

An R6 object of class az_service_principal, inheriting from az_object.

Fields

Methods

Initialization

Creating new objects of this class should be done via the create_service_principal and get_service_principal methods of the ms_graph and az_app classes. Calling the new() method for this class only constructs the R object; it does not call the Microsoft Graph API to create the actual service principal.

See Also

ms_graph, az_app, az_object

Azure Microsoft Graph overview, REST API reference


User in Azure Active Directory

Description

Class representing an AAD user account.

Format

An R6 object of class az_user, inheriting from az_object.

Fields

Methods

Initialization

Creating new objects of this class should be done via the create_user and get_user methods of the ms_graph and az_app classes. Calling the new() method for this class only constructs the R object; it does not call the Microsoft Graph API to create the actual user account.

List methods

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=Inf. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

See Also

ms_graph, az_app, az_group, az_device, az_object

Microsoft Graph overview, REST API reference

Examples

## Not run: 

gr <- get_graph_login()

# my user account
gr$get_user()

# another user account
usr <- gr$get_user("myname@aadtenant.com")

grps <- usr$list_direct_memberships()
head(grps)

# owned objects
usr$list_owned_objects()

# owned apps and service principals
usr$list_owned_objects(type=c("application", "servicePrincipal"))

# first 5 objects
usr$list_owned_objects(n=5)

# get the pager object
pager <- usr$list_owned_objects(n=NULL)
pager$value


## End(Not run)

Call the Graph API batch endpoint

Description

Call the Graph API batch endpoint

Usage

call_batch_endpoint(token, requests = list(), depends_on = NULL,
  api_version = getOption("azure_graph_api_version"))

Arguments

token

An Azure OAuth token, of class AzureToken.

requests

A list of graph_request objects, representing individual requests to the Graph API.

depends_on

An optional named vector, or TRUE. See below.

api_version

The API version to use, which will form part of the URL sent to the host.

Details

Use this function to combine multiple requests into a single HTTPS call. This can save significant network latency.

The depends_on argument specifies the dependencies that may exist between requests. The default is to treat the requests as independent, which allows them to be executed in parallel. If depends_on is TRUE, each request is specified as depending on the immediately preceding request. Otherwise, this should be a named vector or list that gives the dependency or dependencies for each request.

There are 2 restrictions on depends_on:

A request list that has dependencies will be executed serially.

Value

A list containing the responses to each request. Each item has components id and status at a minimum. It may also contain headers and body, depending on the specifics of the request.

See Also

graph_request, call_graph_endpoint

Microsoft Graph overview, Batch endpoint documentation

OData documentation on batch requests

Examples

## Not run: 

req1 <- graph_request$new("me")

# a new email message in Outlook
req_create <- graph_request$new("me/messages",
    body=list(
        body=list(
            content="Hello from R",
            content_type="text"
        ),
        subject="Hello",
        toRecipients="bob@example.com"
    ),
    http_verb="POST"
)

# messages in drafts
req_get <- graph_request$new("me/mailFolders/drafts/messages")

# requests are dependent: 2nd list of drafts will include just-created message
call_batch_endpoint(token, list(req_get, req_create, req_get), depends_on=TRUE)

# alternate way: enumerate all requests
call_batch_endpoint(token, list(req_get, req_create, req_get), depends_on=c("2"=1, "3"=2))


## End(Not run)

Call the Microsoft Graph REST API

Description

Call the Microsoft Graph REST API

Usage

call_graph_endpoint(token, operation, ..., options = list(),
  api_version = getOption("azure_graph_api_version"))

call_graph_url(token, url, ..., body = NULL, encode = "json",
  http_verb = c("GET", "DELETE", "PUT", "POST", "HEAD", "PATCH"),
  http_status_handler = c("stop", "warn", "message", "pass"),
  simplify = FALSE, auto_refresh = TRUE)

Arguments

token

An Azure OAuth token, of class AzureToken.

operation

The operation to perform, which will form part of the URL path.

...

Other arguments passed to lower-level code, ultimately to the appropriate functions in httr.

options

A named list giving the URL query parameters.

api_version

The API version to use, which will form part of the URL sent to the host.

url

A complete URL to send to the host.

body

The body of the request, for PUT/POST/PATCH.

encode

The encoding (really content-type) for the request body. The default value "json" means to serialize a list body into a JSON object. If you pass an already-serialized JSON object as the body, set encode to "raw".

http_verb

The HTTP verb as a string, one of GET, PUT, POST, DELETE, HEAD or PATCH.

http_status_handler

How to handle in R the HTTP status code of a response. "stop", "warn" or "message" will call the appropriate handlers in httr, while "pass" ignores the status code.

simplify

Whether to turn arrays of objects in the JSON response into data frames. Set this to TRUE if you are expecting the endpoint to return tabular data and you want a tabular result, as opposed to a list of objects.

auto_refresh

Whether to refresh/renew the OAuth token if it is no longer valid.

Details

These functions form the low-level interface between R and Microsoft Graph. call_graph_endpoint forms a URL from its arguments and passes it to call_graph_url.

If simplify is TRUE, call_graph_url will exploit the ability of jsonlite::fromJSON to convert arrays of objects into R data frames. This can be useful for REST calls that return tabular data. However, it can also cause problems for paged lists, where each page will be turned into a separate data frame; as the individual objects may not have the same fields, the resulting data frames will also have differing columns. This will cause base R's rbind to fail when binding the pages together. When processing paged lists, AzureGraph will use vctrs::vec_rbind instead of rbind when the vctrs package is available; vec_rbind does not have this problem. For safety, you should only set simplify=TRUE when vctrs is installed.

Value

If http_status_handler is one of "stop", "warn" or "message", the status code of the response is checked. If an error is not thrown, the parsed content of the response is returned with the status code attached as the "status" attribute.

If http_status_handler is "pass", the entire response is returned without modification.

See Also

httr::GET, httr::PUT, httr::POST, httr::DELETE, httr::stop_for_status, httr::content


Login to Azure Active Directory Graph

Description

Login to Azure Active Directory Graph

Usage

create_graph_login(tenant = "common", app = NULL, password = NULL,
  username = NULL, certificate = NULL, auth_type = NULL, version = 2,
  host = "https://graph.microsoft.com/",
  aad_host = "https://login.microsoftonline.com/", scopes = ".default",
  config_file = NULL, token = NULL, ...)

get_graph_login(tenant = "common", selection = NULL, app = NULL,
  scopes = NULL, auth_type = NULL, refresh = TRUE)

delete_graph_login(tenant = "common", confirm = TRUE)

list_graph_logins()

Arguments

tenant

The Azure Active Directory tenant for which to obtain a login client. Can be a name ("myaadtenant"), a fully qualified domain name ("myaadtenant.onmicrosoft.com" or "mycompanyname.com"), or a GUID. The default is to login via the "common" tenant, which will infer your actual tenant from your credentials.

app

The client/app ID to use to authenticate with Azure Active Directory. The default is to login interactively using the Azure CLI cross-platform app, but you can supply your own app credentials as well.

password

If auth_type == "client_credentials", the app secret; if auth_type == "resource_owner", your account password.

username

If auth_type == "resource_owner", your username.

certificate

If 'auth_type == "client_credentials", a certificate to authenticate with. This is a more secure alternative to using an app secret.

auth_type

The OAuth authentication method to use, one of "client_credentials", "authorization_code", "device_code" or "resource_owner". If NULL, this is chosen based on the presence of the username and password arguments.

version

The Azure Active Directory version to use for authenticating.

host

Your Microsoft Graph host. Defaults to ⁠https://graph.microsoft.com/⁠. Change this if you are using a government or private cloud.

aad_host

Azure Active Directory host for authentication. Defaults to ⁠https://login.microsoftonline.com/⁠. Change this if you are using a government or private cloud.

scopes

The Microsoft Graph scopes (permissions) to obtain for this Graph login. For create_graph_login, this is used only for version=2. For get_graph_login, set this to NA to require an AAD v1.0 token.

config_file

Optionally, a JSON file containing any of the arguments listed above. Arguments supplied in this file take priority over those supplied on the command line. You can also use the output from the Azure CLI ⁠az ad sp create-for-rbac⁠ command.

token

Optionally, an OAuth 2.0 token, of class AzureAuth::AzureToken. This allows you to reuse the authentication details for an existing session. If supplied, all other arguments to create_graph_login will be ignored.

...

Other arguments passed to ms_graph$new().

selection

For get_graph_login, if you have multiple logins for a given tenant, which one to use. This can be a number, or the input MD5 hash of the token used for the login. If not supplied, get_graph_login will print a menu and ask you to choose a login.

refresh

For get_graph_login, whether to refresh the authentication token on loading the client.

confirm

For delete_graph_login, whether to ask for confirmation before deleting.

Details

create_graph_login creates a login client to authenticate with Microsoft Graph, using the supplied arguments. The authentication token is obtained using get_azure_token, which automatically caches and reuses tokens for subsequent sessions.

For interactive use, you would normally not supply the username and password arguments. Omitting them will prompt create_graph_login to authenticate you with AAD using your browser, which is the recommended method. If you don't have a browser available to your R session, for example if you're using RStudio Server or Azure Databricks, you can specify ⁠auth_type="device_code⁠".

For non-interactive use, for example if you're calling AzureGraph in a deployment pipeline, the recommended authentication method is via client credentials. For this method, you supply only the password argument, which should contain the client secret for your app registration. You must also specify your own app registration ID, in the app argument.

The AzureAuth package has a vignette that goes into more detail on these authentication scenarios.

get_graph_login returns a previously created login client. If there are multiple existing clients, you can specify which client to return via the selection, app, scopes and auth_type arguments. If you don't specify which one to return, it will pop up a menu and ask you to choose one.

One difference between create_graph_login and get_graph_login is the former will delete any previously saved credentials that match the arguments it was given. You can use this to force AzureGraph to remove obsolete tokens that may be lying around.

Value

For get_graph_login and create_graph_login, an object of class ms_graph, representing the login client. For list_graph_logins, a (possibly nested) list of such objects.

If the AzureR data directory for saving credentials does not exist, get_graph_login will throw an error.

See Also

ms_graph, AzureAuth::get_azure_token for more details on authentication methods

AzureAuth vignette on authentication scenarios

Microsoft Graph overview, REST API reference

Examples

## Not run: 

# without any arguments, this will create a client using your AAD organisational account
az <- create_graph_login()

# retrieve the login in subsequent sessions
az <- get_graph_login()

# this will create an Microsoft Graph client for the tenant 'mytenant.onmicrosoft.com',
# using the client_credentials method
az <- create_graph_login("mytenant", app="{app_id}", password="{password}")

# you can also login using credentials in a json file
az <- create_graph_login(config_file="~/creds.json")

# creating and obtaining a login with specific scopes
create_graph_login("mytenant", scopes=c("User.Read", "Files.ReadWrite.All"))
get_graph_login("mytenant", scopes=c("User.Read", "Files.ReadWrite.All"))

# to use your personal account, set the tenant to one of the following
create_graph_login("9188040d-6c67-4c5b-b112-36a304b66dad")
create_graph_login("consumers")  # requires AzureAuth 1.3.0


## End(Not run)

Get the list of values from a Graph pager object

Description

Get the list of values from a Graph pager object

Usage

extract_list_values(pager, n = Inf)

Arguments

pager

An object of class ms_graph_pager, which is an iterator for a list of paged query results.

n

The number of items from the list to return. Note this is not the number of pages (each page will usually contain multiple items). The default value of Inf extracts all the values from the list, leaving the pager empty. If this is NULL, the pager itself is returned.

Details

This is a convenience function to perform the common task of extracting all or some of the items from a paged response.

Value

If n is Inf or a number, the items from the paged query results. The format of the returned value depends on the pager settings. This will either be a nested list containing the properties for each of the items; a list of R6 objects; or a data frame. If the pager is empty, an error is thrown.

If n is NULL, the pager itself is returned.

See Also

ms_graph_pager, ms_object, call_graph_endpoint

Examples

## Not run: 

firstpage <- call_graph_endpoint(token, "me/memberOf")
pager <- ms_graph_pager$new(token, firstpage)
extract_list_values(pager)

# trying to extract values a 2nd time will fail
try(extract_list_values(pager))


## End(Not run)

Find the R6 class for a Graph object

Description

Find the R6 class for a Graph object

Usage

find_class_generator(props, type_filter = NULL, default_generator = ms_object)

Arguments

props

A list of object properties, generally the result of a Graph API call.

type_filter

An optional vector of types by which to filter the result.

default_generator

The default class generator to use, if a match couldn't be found.

Details

This function maps Graph objects to AzureGraph classes.

Value

An R6 class generator for the appropriate AzureGraph class. If no matching R6 class could be found, the default generator is returned. If type_filter is provided, but the matching R6 class isn't in the filter, NULL is returned.


Format a Microsoft Graph or Azure object

Description

Miscellaneous functions for printing Microsoft Graph and Azure R6 objects

Usage

format_public_fields(env, exclude = character(0))

format_public_methods(env)

Arguments

env

An R6 object's environment for printing.

exclude

Objects in env to exclude from the printout.

Details

These are utilities to aid in printing R6 objects created by this package or its descendants. They are not meant to be called by the user.


Microsoft Graph request

Description

Class representing a request to the Microsoft Graph API. Currently this is used only in building a batch call.

Format

An R6 object of class graph_request.

Methods

Details

The initialize() method takes the following arguments, representing the components of a HTTPS request:

This class is currently used only for building batch calls. Future versions of AzureGraph may be refactored to use it in general API calls as well.

See Also

call_batch_endpoint

Microsoft Graph overview, Batch endpoint documentation

Examples

graph_request$new("me")

# a new email message in Outlook
graph_request$new("me/messages",
    body=list(
        body=list(
            content="Hello from R",
            content_type="text"
        ),
        subject="Hello",
        toRecipients="bob@example.com"
    ),
    http_verb="POST"
)

Informational functions

Description

These functions return whether the object is of the corresponding class.

Usage

is_app(object)

is_service_principal(object)

is_user(object)

is_group(object)

is_directory_role(object)

is_aad_object(object)

is_msgraph_object(object)

Arguments

object

An R object.

Value

A boolean.


Microsoft Graph

Description

Base class for interacting with Microsoft Graph API.

Format

An R6 object of class ms_graph.

Methods

Authentication

The recommended way to authenticate with Microsoft Graph is via the create_graph_login function, which creates a new instance of this class.

To authenticate with the ms_graph class directly, provide the following arguments to the new method:

App creation

The create_app method creates a new app registration. By default, a new app will have a randomly generated strong password with duration of 2 years. To skip assigning a password, set the add_password argument to FALSE.

The certificate argument allows authenticating via a certificate instead of a password. This should be a character string containing the certificate public key (aka the CER file). Alternatively it can be an list, or an object of class AzureKeyVault::stored_cert representing a certificate stored in an Azure Key Vault. See the examples below.

A new app will also have a service principal created for it by default. To disable this, set create_service_principal=FALSE.

List methods

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=Inf. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

See Also

create_graph_login, get_graph_login

Microsoft Graph overview, REST API reference

Examples

## Not run: 

# start a new Graph session
gr <- ms_graph$new(tenant="myaadtenant.onmicrosoft.com")

# authenticate with credentials in a file
gr <- ms_graph$new(config_file="creds.json")

# authenticate with device code
gr <- ms_graph$new(tenant="myaadtenant.onmicrosoft.com", app="app_id", auth_type="device_code")

# retrieve an app registration
gr$get_app(app_id="myappid")

# create a new app and associated service principal, set password duration to 10 years
app <- gr$create_app("mynewapp", password_duration=10)

# delete the app
gr$delete_app(app_id=app$properties$appId)
# ... but better to call the object's delete method directly
app$delete()

# create an app with authentication via a certificate
cert <- readLines("mycert.cer")
gr$create_app("mycertapp", password=FALSE, certificate=cert)

# retrieving your own user details (assuming interactive authentication)
gr$get_user()

# retrieving another user's details
gr$get_user("username@myaadtenant.onmicrosoft.com")
gr$get_user(email="firstname.lastname@mycompany.com")
gr$get_user(name="Hong Ooi")

# get an AAD object (a group)
id <- gr$get_user()$list_group_memberships()[1]
gr$get_aad_object(id)

# list the users in the tenant
gr$list_users()

# list (guest) users with a 'gmail.com' email address
gr$list_users(filter="endsWith(mail,'gmail.com')")

# list Microsoft 365 groups
gr$list_groups(filter="groupTypes/any(c:c eq 'Unified')")


## End(Not run)

Pager object for Graph list results

Description

Class representing an iterator for a set of paged query results.

Format

An R6 object of class ms_graph_pager.

Fields

Methods

Active bindings

Initialization

The recommended way to create objects of this class is via the ms_object$get_list_pager() method, but it can also be initialized directly. The arguments to the new() method are:

Value

The value active binding returns the page values for each iteration of the pager. This can take one of 3 forms, based on the initial format of the first page and the generate_objects argument.

If the first page of results is a data frame (each item has been converted into a row), then the pager will return results as data frames. In this case, the output field is automatically set to "data.frame" and the generate_objects initialization argument is ignored. Usually this will be the case when the results are meant to represent external data, eg items in a SharePoint list.

If the first page of results is a list, the generate_objects argument sets whether to convert the items in each page into R6 objects defined by the AzureGraph class framework. If generate_objects is TRUE, the output field is set to "object", and if generate_objects is FALSE, the output field is set to "list".

See Also

ms_object, extract_list_values

Microsoft Graph overview, Paging documentation

Examples

## Not run: 

# list direct memberships
firstpage <- call_graph_endpoint(token, "me/memberOf")

pager <- ms_graph_pager$new(token, firstpage)
pager$has_data()
pager$value

# once all the pages have been returned
isFALSE(pager$has_data())
is.null(pager$value)

# returning items, 1 per page, as raw lists of properties
firstpage <- call_graph_endpoint(token, "me/memberOf", options=list(`$top`=1))
pager <- ms_graph_pager$new(token, firstpage, generate_objects=FALSE)
lst <- NULL
while(pager$has_data())
    lst <- c(lst, pager$value)

# returning items as a data frame
firstdf <- call_graph_endpoint(token, "me/memberOf", options=list(`$top`=1),
                               simplify=TRUE)
pager <- ms_graph_pager$new(token, firstdf)
df <- NULL
while(pager$has_data())
    df <- vctrs::vec_rbin(df, pager$value)


## End(Not run)

Microsoft Graph object

Description

Base class representing a object in Microsoft Graph. All other Graph object classes ultimately inherit from this class.

Format

An R6 object of class ms_object.

Fields

Methods

Initialization

Objects of this class should not be created directly. Instead, create an object of the appropriate subclass.

List methods

All ⁠list_*⁠ methods have filter and n arguments to limit the number of results. The former should be an OData expression as a string to filter the result set on. The latter should be a number setting the maximum number of (filtered) results to return. The default values are filter=NULL and n=Inf. If n=NULL, the ms_graph_pager iterator object is returned instead to allow manual iteration over the results.

Support in the underlying Graph API for OData queries is patchy. Not all endpoints that return lists of objects support filtering, and if they do, they may not allow all of the defined operators. If your filtering expression results in an error, you can carry out the operation without filtering and then filter the results on the client side.

Paged results

Microsoft Graph returns lists in pages, with each page containing a subset of objects and a link to the next page. AzureGraph provides an iterator-based API that lets you access each page individually, or collect them all into a single object.

To create a new pager object, call the get_list_pager() method with the following arguments:

This returns an object of class ms_graph_pager, which is an iterator for the set of paged results. Each call to the object's value active binding yields the next page. When all pages have been returned, value contains NULL.

The format of the returned values can take one of 3 forms, based on the initial format of the first page and the generate_objects argument.

If the first page of results is a data frame (each item has been converted into a row), then the pager will return results as data frames. In this case, the output field is automatically set to "data.frame" and the generate_objects initialization argument is ignored. Usually this will be the case when the results are meant to represent external data, eg items in a SharePoint list.

If the first page of results is a list, the generate_objects argument sets whether to convert the items in each page into R6 objects defined by the AzureGraph class framework. If generate_objects is TRUE, the output field is set to "object", and if generate_objects is FALSE, the output field is set to "list".

You can also call the extract_list_values() function to get all or some of the values from a pager, without having to manually combine the pages together.

Deprecated methods

The following methods are private and deprecated, and form the older AzureGraph API for accessing paged results. They will eventually be removed.

See Also

ms_graph, az_object, ms_graph_pager, extract_list_values

Microsoft Graph overview, REST API reference


Miscellaneous utility functions

Description

Miscellaneous utility functions

Usage

named_list(lst = NULL, name_fields = "name")

is_empty(x)

Arguments

lst

A named list of objects.

name_fields

The components of the objects in lst, to be used as names.

x

For is_empty, An R object.

Details

named_list extracts from each object in lst, the components named by name_fields. It then constructs names for lst from these components, separated by a "/".

Value

For named_list, the list that was passed in but with names. An empty input results in a named list output: a list of length 0, with a names attribute.

For is_empty, whether the length of the object is zero (this includes the special case of NULL).


Extensible registry of Microsoft Graph classes that AzureGraph supports

Description

Extensible registry of Microsoft Graph classes that AzureGraph supports

Usage

register_graph_class(name, R6_generator, check_function)

Arguments

name

The name of the Graph class, eg "user", "servicePrincipal", etc.

R6_generator

An R6 class generator corresponding to this Graph class.

check_function

A boolean function that checks if a list of properties is for an object of this class.

Details

As written, AzureGraph knows about a subset of all the object classes contained in Microsoft Graph. These are mostly the classes originating from Azure Active Directory: users, groups, app registrations, service principals and registered devices.

You can extend AzureGraph by writing your own R6 class that inherits from ms_object. If so, you should also register your class by calling register_graph_class and providing the generator object, along with a check function. The latter should accept a list of object properties (as obtained from the Graph REST API), and return TRUE/FALSE based on whether the object is of your class.

Value

An invisible vector of registered class names.

Examples

## Not run: 

# built-in 'az_user' class, for an AAD user object
register_graph_class("user", az_user,
   function(props) !is.null(props$userPrincipalName))


## End(Not run)