msgraph.go

msgraph.go

v1.0	beta

(The online references at pkg.go.dev above are not shown due to huge size of packages - #23)

Introduction

Microsoft Graph client library for Go. Still in PoC or pre-alpha stage. Don't use in production.

The library code is auto-generated from the REST API specification available at https://graph.microsoft.com/v1.0/$metadata.

The code generator is written in pure Go, in contrast to the official code generator heavily relying on C# and non-portable .NET Framework.

v0.x.x releases

See GitHub releases for all release tags and release notes, and pkg.go.dev for all Go module versions available for your applications.

Until v1.0.0, all types of changes might be included in every release: bug fixes, new features, even incompatible API updates.

Usage

You can choose API version when importing msgraph package:

import msgraph "github.com/yaegashi/msgraph.go/v1.0"

import msgraph "github.com/yaegashi/msgraph.go/beta"

You could benefit from better IDE assisted coding experience because Graph API specs are completely translated to Go codes by msgraph.go.

Code examples in the repository:

• cmd/msgraph-me: Show the profile of signed in user (me) and download files in the root folder of their drive
• cmd/msgraph-usergroup: Graph user/group manipulation example
• cmd/msgraph-sshpubkey: Manage SSH public keys in the open extension of graph user resources
• cmd/msgraph-spoget: Download a file with SharePoint Online URL

Hacking

Run go generate ./gen to download the metadata and generate library code from it.

$ go generate ./gen
2020/08/02 19:46:20 Downloading https://graph.microsoft.com/v1.0/$metadata to metadata/v1.0.xml
2020/08/02 19:46:20 metadata/v1.0.xml already exists, skipping
2020/08/02 19:46:21 Downloading https://graph.microsoft.com/beta/$metadata to metadata/beta.xml
2020/08/02 19:46:21 metadata/beta.xml already exists, skipping
2020/08/02 19:46:21 Creating directory ../v1.0
2020/08/02 19:46:21 Removing ../v1.0/ModelAverage.go
2020/08/02 19:46:21 Removing ../v1.0/RequestSchema.go
2020/08/02 19:46:21 Removing ../v1.0/RequestAndroid.go.go
...
2020/08/02 19:47:06 Creating ../v1.0/extensions.go
2020/08/02 19:47:06 Creating ../v1.0/msgraph.go
2020/08/02 19:47:06 Creating ../v1.0/const.go
2020/08/02 19:47:06 Creating ../v1.0/EnumAction.gonEnum.go
...
2020/08/02 19:47:07 Formatting ../v1.0/ModelMedia.go
2020/08/02 19:47:07 Formatting ../v1.0/RequestWorkbookFunctionsN.go
2020/08/02 19:47:07 Formatting ../v1.0/EnumReject.go

(Currently code generation from the latest metadata is broken - #22)

Todo

• Save indented metadata.xml
• Support Action elements in metadata
• Support Function elements in metadata
• Support batch requests
• Access to additional properties like @odata.type @odata.id
• Split output into multiple files
• Generate camel cases in golang manner (IpAddress -> IPAddress)
• Provide easy way to generate pointers to literals
• Provide easy way to generate pointers to constants
• Provide easy way to add queries like $expand $select $filter
• Every request method should take a ctx as the first arg for better control
• Online API docs (the output is too big for pkg.go.dev to handle - #23)
• Unit tests
• CI
• Persist OAuth2 tokens in file
• Persist OAuth2 tokens in object storage like Azure Blob
• OAuth2 device auth grant
• OAuth2 client credentials grant
• Use string for EnumType (pointed out in #6)
• Reduce number of generated files (#11)
• Provide easy way to add HTTP headers like Prefer: outlook.timezone="Tokyo Standard Time"
• Support max number of pages to retrieve from a collection
• Support Windows time zone names in DateTimeTimeZone (utilize wtz.go)

References

• Microsoft Graph
• Microsoft Graph REST API reference
• Microsoft Graph SDKs - Requirements and Design
• Microsoft Graph SDK Code Generator
• GitHub repository search for msgraph in Go
• Microsoft Graph API Library for Go (presentation in Japanese)
• msgraph.go demo - SharePoint Online + Microsoft Flow + GitLab CI (screencast in YouTube)

Applications

• Terraform Provider for Microsoft Graph