github.com/yaegashi/msgraph.go@v0.1.4/README.md (about) 1 # msgraph.go 2 3 [![](https://github.com/yaegashi/msgraph.go/workflows/go%20generate%20test/badge.svg?branch=master)](https://github.com/yaegashi/msgraph.go/actions) 4 5 |v1.0|beta| 6 |---|---| 7 |[![pkg.go.dev](https://pkg.go.dev/badge/github.com/yaegashi/msgraph.go/v1.0)](https://pkg.go.dev/github.com/yaegashi/msgraph.go/v1.0)|[![pkg.go.dev](https://pkg.go.dev/badge/github.com/yaegashi/msgraph.go/beta)](https://pkg.go.dev/github.com/yaegashi/msgraph.go/beta)| 8 9 (The online references at pkg.go.dev above are not shown due to huge size of packages - [#23](https://github.com/yaegashi/msgraph.go/issues/23)) 10 11 ## Introduction 12 13 [Microsoft Graph] client library for Go. Still in PoC or pre-alpha stage. 14 Don't use in production. 15 16 The library code is auto-generated from the REST API specification 17 available at https://graph.microsoft.com/v1.0/$metadata. 18 19 The code generator is written in pure Go, 20 in contrast to [the official code generator][Microsoft Graph SDK Code Generator] 21 heavily relying on C# and non-portable .NET Framework. 22 23 ## v0.x.x releases 24 25 See [GitHub releases](https://github.com/yaegashi/msgraph.go/releases) 26 for all release tags and release notes, 27 and [pkg.go.dev](https://pkg.go.dev/mod/github.com/yaegashi/msgraph.go) 28 for all Go module versions available for your applications. 29 30 Until v1.0.0, all types of changes might be included in every release: 31 bug fixes, new features, even incompatible API updates. 32 33 ## Usage 34 35 You can choose API version when importing `msgraph` package: 36 37 ```go 38 import msgraph "github.com/yaegashi/msgraph.go/v1.0" 39 ``` 40 41 ```go 42 import msgraph "github.com/yaegashi/msgraph.go/beta" 43 ``` 44 45 You could benefit from better IDE assisted coding experience 46 because Graph API specs are completely translated to Go codes by msgraph.go. 47 48 ![](assets/msgraph.go-vscode2.gif) 49 50 Code examples in the repository: 51 52 - [cmd/msgraph-me](cmd/msgraph-me): Show the profile of signed in user (me) and download files in the root folder of their drive 53 - [cmd/msgraph-usergroup](cmd/msgraph-usergroup): Graph user/group manipulation example 54 - [cmd/msgraph-sshpubkey](cmd/msgraph-sshpubkey): Manage SSH public keys in the open extension of graph user resources 55 - [cmd/msgraph-spoget](cmd/msgraph-spoget): Download a file with SharePoint Online URL 56 57 ## Hacking 58 59 Run `go generate ./gen` to download the metadata and generate library code from it. 60 61 ```console 62 $ go generate ./gen 63 2020/08/02 19:46:20 Downloading https://graph.microsoft.com/v1.0/$metadata to metadata/v1.0.xml 64 2020/08/02 19:46:20 metadata/v1.0.xml already exists, skipping 65 2020/08/02 19:46:21 Downloading https://graph.microsoft.com/beta/$metadata to metadata/beta.xml 66 2020/08/02 19:46:21 metadata/beta.xml already exists, skipping 67 2020/08/02 19:46:21 Creating directory ../v1.0 68 2020/08/02 19:46:21 Removing ../v1.0/ModelAverage.go 69 2020/08/02 19:46:21 Removing ../v1.0/RequestSchema.go 70 2020/08/02 19:46:21 Removing ../v1.0/RequestAndroid.go.go 71 ... 72 2020/08/02 19:47:06 Creating ../v1.0/extensions.go 73 2020/08/02 19:47:06 Creating ../v1.0/msgraph.go 74 2020/08/02 19:47:06 Creating ../v1.0/const.go 75 2020/08/02 19:47:06 Creating ../v1.0/EnumAction.gonEnum.go 76 ... 77 2020/08/02 19:47:07 Formatting ../v1.0/ModelMedia.go 78 2020/08/02 19:47:07 Formatting ../v1.0/RequestWorkbookFunctionsN.go 79 2020/08/02 19:47:07 Formatting ../v1.0/EnumReject.go 80 ``` 81 82 (Currently code generation from the latest metadata is broken - [#22](https://github.com/yaegashi/msgraph.go/issues/22)) 83 84 ## Todo 85 86 - [x] Save indented metadata.xml 87 - [x] Support Action elements in metadata 88 - [ ] Support Function elements in metadata 89 - [ ] Support batch requests 90 - [x] Access to additional properties like `@odata.type` `@odata.id` 91 - [x] Split output into multiple files 92 - [x] Generate camel cases in golang manner (`IpAddress` -> `IPAddress`) 93 - [x] Provide easy way to generate pointers to literals 94 - [x] Provide easy way to generate pointers to constants 95 - [x] Provide easy way to add queries like `$expand` `$select` `$filter` 96 - [x] Every request method should take a ctx as the first arg for better control 97 - [ ] Online API docs (the output is too big for pkg.go.dev to handle - [#23](https://github.com/yaegashi/msgraph.go/issues/23)) 98 - [ ] Unit tests 99 - [x] CI 100 - [x] Persist OAuth2 tokens in file 101 - [x] Persist OAuth2 tokens in object storage like Azure Blob 102 - [x] OAuth2 device auth grant 103 - [x] OAuth2 client credentials grant 104 - [x] Use string for EnumType (pointed out in #6) 105 - [x] Reduce number of generated files (#11) 106 - [x] Provide easy way to add HTTP headers like `Prefer: outlook.timezone="Tokyo Standard Time"` 107 - [ ] Support max number of pages to retrieve from a collection 108 - [x] Support Windows time zone names in DateTimeTimeZone (utilize [wtz.go](https://github.com/yaegashi/wtz.go)) 109 110 ## References 111 112 - [Microsoft Graph] 113 - [Microsoft Graph REST API reference] 114 - [Microsoft Graph SDKs - Requirements and Design] 115 - [Microsoft Graph SDK Code Generator] 116 - [GitHub repository search for msgraph in Go] 117 - [Microsoft Graph API Library for Go] (presentation in Japanese) 118 - [msgraph.go demo - SharePoint Online + Microsoft Flow + GitLab CI] (screencast in YouTube) 119 120 [Microsoft Graph]: https://developer.microsoft.com/en-us/graph 121 [Microsoft Graph REST API reference]: https://docs.microsoft.com/en-us/graph/api/overview 122 [Microsoft Graph SDKs - Requirements and Design]: https://microsoftgraph.github.io/msgraph-sdk-design/ 123 [Microsoft Graph SDK Code Generator]: https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator 124 [GitHub repository search for msgraph in Go]: https://github.com/search?l=Go&q=msgraph&type=Repositories 125 [Microsoft Graph API Library for Go]: https://www.slideshare.net/yaegashi/microsoft-graph-api-library-for-go 126 [msgraph.go demo - SharePoint Online + Microsoft Flow + GitLab CI]: https://www.youtube.com/watch?v=DwKk405XyF4 127 128 ## Applications 129 130 - [Terraform Provider for Microsoft Graph](https://github.com/yaegashi/terraform-provider-msgraph)