Skip to content

Commit 9363eac

Browse files
peombwapeombwa
authored
Merge pull request #386 from microsoftgraph/po/readmeUpdate
ReadMe Update
2 parents 2d988e2 + 910437c commit 9363eac

File tree

1 file changed

+69
-97
lines changed

1 file changed

+69
-97
lines changed

‎README.md‎

Lines changed: 69 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,112 @@
11
# Microsoft Graph PowerShell SDK Preview
2-
The Microsoft Graph PowerShell SDK is a collection of PowerShell modules that contain cmdlets for calling Microsoft Graph.
2+
The Microsoft Graph PowerShell SDK is a collection of PowerShell modules that contain commands for calling Microsoft Graph service.
33

4-
## Installing the Microsoft.Graph Module
4+
# Modules
5+
The table below contains our Microsoft Graph rollup module. This module installs all the service modules as its dependencies.
6+
Description | Module Name | PowerShell Gallery Link
7+
----------------- | ----------------- | ------------------------
8+
Microsoft Graph | `Microsoft.Graph` | [![Mg]][MgGallery]
59

6-
The modules are now published on the PowerShell Gallery. Installing is as simple as:
10+
For a list of modules found in this repository, see the [Microsoft Graph Graph PowerShell modules](https://github.com/microsoftgraph/msgraph-sdk-powershell/wiki/MS-Graph-PowerShell-Modules) document.
711

8-
```ps
9-
Install-module Microsoft.Graph
10-
```
12+
## Installation
13+
### PowerShell Gallery
1114

12-
There are a set of samples in the `samples` folder to help getting started with the library. If you have an older version of these modules installed, there are uninstall instructions in the [InstallModule](./samples/0-InstallModule.ps1) script.
15+
All the modules are published on [PowerShell Gallery](https://www.powershellgallery.com/packages/Microsoft.Graph). Installing is as simple as:
1316

14-
## Generate Module
17+
```ps
18+
Install-Module Microsoft.Graph
19+
```
1520

16-
### Prerequisite
21+
If you are upgrading from our preview modules, run `Install-Module` with AllowClobber and Force parameter to avoid command name conflicts:
22+
```ps
23+
Install-Module Microsoft.Graph -AllowClobber -Force
24+
```
25+
There are a set of samples in the `samples` folder to help in getting started with the library. If you have an older version of these modules installed, there are extra uninstall instructions in the [InstallModule](./samples/0-InstallModule.ps1) script.
1726

18-
1. [Download](https://github.com/PowerShell/PowerShell/releases/tag/v6.2.3) and install PowerShell Core.
27+
## Usage
1928

20-
2. Install AutoRest.
29+
1. Authentication
30+
31+
The SDK supports two types of authentication: delegated access, and app-oly access.
32+
- Delegated access via Device Code Flow.
2133

22-
```ps
23-
npm install -g "@autorest/autorest"
24-
```
34+
```ps
35+
Connect-Graph -Scopes "User.Read.All", "Group.ReadWrite.All"
36+
```
2537
26-
3. Create an [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/artifacts/tutorials/private-powershell-library?view=azure-devops) Artifacts Feed or host a local [Nuget.Server](https://docs.microsoft.com/en-us/nuget/hosting-packages/nuget-server), and register it as a local PowerShell repository using `Register-PSRepository` command. Once done, take note of the `RepositoryName` and `APIKey`. You can always get the repository name by running `Get-PSRepository`.
27-
This will be used as a temporary repository to publish generated modules in order to specify them as dependencies for `Microsoft.Graph` roll-up module.
38+
- App only access via Client Credential with a certificate.
2839
29-
***N.B - Once we have a preview version of the modules in PowerShell Gallery, this step won't be needed.***
40+
The certificate will be loaded from `Cert:\CurrentUser\My\` store. Ensure the certificate is present in the store before calling `Connect-Graph`.
41+
42+
You can pass either `-CertificateThumbprint` or `-CertificateName` to `Connect-Graph`.
3043
31-
### Generation Steps
44+
```ps
45+
# Using -CertificateThumbprint
46+
Connect-Graph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateThumbprint "YOUR_CERT_THUMBPRINT"
47+
```
3248
33-
1. Clone the [msgraph-sdk-powershell](https://github.com/microsoftgraph/msgraph-sdk-powershell) repo locally.
49+
or
3450
35-
```ps
36-
git clone https://github.com/microsoftgraph/msgraph-sdk-powershell.git -b dev
37-
```
51+
```ps
52+
# Using -CertificateName
53+
Connect-Graph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateName "YOUR_CERT_SUBJECT"
54+
```
3855
39-
2. Generate, pack and optionally publish `Microsoft.Graph.Authentication` module.
56+
2. List users in your tenant.
4057
4158
```ps
42-
. \msgraph-sdk-powershell\tools\GenerateAuthenticationModule.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
59+
Get-User -Top 10 -Property Id, DisplayName, BusinessPhones | Format-Table Id, DisplayName, BusinessPhones
4360
```
4461
45-
3. Generate, pack and optionally publish Microsoft Graph service PowerShell modules by tags. For a complete list of tags, see [OpenApiSplice](https://github.com/microsoftgraph/msgraph-openapi-introspection).
46-
47-
Edit `.\config\ModulesMapping.jsonc` by adding key-value pairs of the tags you want to generate modules for. The key is the name of the module to be generated and the value is a regex expression that will be used to query [OpenApiSplice](https://github.com/microsoftgraph/msgraph-openapi-introspection) for an OpenAPI document for your module.
48-
49-
To generate v1.0 modules, run the following script:
62+
3. Filter a user in your tenant.
5063
5164
```ps
52-
. \msgraph-sdk-powershell\tools\GenerateModules.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
65+
$user = Get-MgUser -Filter "displayName eq 'Megan Bowen'"
5366
```
5467
55-
To generate beta endpoint modules, add `-BetaGraphVersion` switch when running `GenerateModules.ps1`.
56-
57-
This performs the following actions :
58-
- Generates the modules specified in `.\config\ModulesMapping.jsonc` in `.\msgraph-sdk-powershell\src\{GraphVersion}\{Module-Name}\{Module-Name}\`.
59-
- Adds appropriate dependencies to the generated modules.
60-
- Packs and optionally publishes the modules to the specified repository as `.nupkg` files. The generated `nupkg` can be found in `.\msgraph-sdk-powershell\artifacts\{GraphVersion}\{Module-Name}\`.
61-
62-
4. Generate, pack and optionally publish `Microsoft.Graph` roll-up module.
68+
4. Create a new app registration.
6369
6470
```ps
65-
. \msgraph-sdk-powershell\tools\GenerateRollUpModule.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
71+
New-MgApplication -DisplayName "ScriptedGraphPSApp" `
72+
-SignInAudience "AzureADMyOrg" `
73+
-Web @{ RedirectUris = "https://localhost"}
6674
```
6775
68-
To generate a roll-up module for Microsoft Graph beta modules, add `-BetaGraphVersion` switch when running `GenerateRollUpModule.ps1`.
69-
70-
The above script generates a `Microsoft.Graph` module manifest with the generated Microsoft Graph service modules specified in `.\config\ModulesMapping.jsonc` and `Microsoft.Graph.Authentication` module as its dependencies.
71-
72-
5. Optionally, manually publish modules from an artifacts location.
76+
5. Sign out of the current logged-in context i.e. app only or delegated access.
7377
7478
```ps
75-
. \msgraph-sdk-powershell\tools\PublishModule.ps1 -Modules "Graph", "Authentication", "Subscriptions", "Teams" -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ArtifactsLocation {ArtifactsLocation}
76-
```
77-
78-
#### Common Generation Scripts Parameters
79-
80-
- ***`-ModuleVersion`***: The version of the module to generate. This defaults to `0.1.0` when not specified.
81-
- ***`-ModulePreviewNumber`***: An optional preview number of the module(s) to generate. When not specified, the module is generated as a non preview module(s) of the `ModuleVersion`.
82-
- ***`-Publish`***: An optional switch that publishes generated module(s) to the specified `RepositoryName`. This used when module dependencies are not locally installed in your machine.
83-
- ***`-BetaGraphVersion`***: A switch that indicates tells the generation scripts to generate beta modules of Microsoft Graph. If not specified, the generation scripts will generate v1.0 modules.
84-
85-
## Run Generated Modules
86-
87-
1. By default, the generated modules should already be installed on your PC in `%UserProfile%\Documents\PowerShell\Modules` as part of the generation process. If it's not present or you want to install the modules on another machine, then install them as such by specifying your repository name:
88-
89-
```ps
90-
Install-Module Microsoft.Graph -Repository {RepositoryName} # v1.0 modules
91-
or
92-
Install-Module Microsoft.Graph.Beta -Repository {RepositoryName} # beta modules
79+
Disconnect-Graph
9380
```
81+
## API Version
82+
By default, the SDK uses the Microsoft Graph REST API v1.0. You can change this by using the `Select-MgProfile` command. This reloads all modules and only loads commands that call beta endpoint.
9483
95-
2. Authenticate to Microsoft Identity to get an access token to call Microsoft Graph modules.
96-
- Delegated access via Device Code Flow.
97-
98-
```ps
99-
Connect-Graph -Scopes "User.Read.All"
100-
```
101-
102-
- App only access via Client Credential Flow with a certificate.
103-
104-
```ps
105-
# Replace CN=DaemonConsoleCert with your certificate name.
106-
Connect-Graph -ClientId ClientId -TenantId TenantId -CertificateName "CN=DaemonConsoleCert"
107-
```
108-
109-
3. Call `Get-User` command.
84+
```ps
85+
Select-MgProfile -Name "beta"
86+
```
11087

111-
```ps
112-
# Authenticate for delegated access.
113-
Connect-Graph
88+
## Troubleshooting Permission Related Errors
11489

115-
Get-User -Top 10 -Select Id, DisplayName, BusinessPhones | Format-Table Id, DisplayName, BusinessPhones
116-
```
90+
When working with various operations in the Graph, you may encounter an error such as "Insufficient privileges to complete the operation." For example, this particular error can occur when using the `New-MgApplication` command if the appropriate permissions are not granted.
11791

118-
4. Call `Get-UserMessage` cmdlet.
92+
If permission related errors occur and the user you authenticated with in the popup has the appropriate permissions to perform the operation try these steps.
11993

120-
```ps
121-
# Authenticate for app only access.
122-
Connect-Graph -ClientId ClientId -TenantId TenantId -CertificateName CertificateName
94+
- You can try running `Disconnect-Graph`, then `Connect-Graph`. Then, run the code that encountered the permission issues to see if it works.
95+
- You can try running `Connect-Graph -ForceRefresh`. This will trigger a refresh of the access token in your cache. MSAL will only refresh the access token in your cache if it has expired (usually an hour), or if you explicitly refresh it via `-ForceRefresh`. Then, run the code that encountered the permission issues to see if it works.
12396

124-
Get-UserMessage -UserId UserId -Top 10 -Skip 10 -Select Id, Subject, CreatedDateTime | Format-Table CreatedDateTime, Subject, Id
125-
```
97+
## Issues
98+
If you find any bugs when using the Microsoft Graph PowerShell modules, please file an issue in our GitHub issues page.
12699

127-
5. Sign out of the current logged in context i.e. app only or delegated access.
100+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
128101

129-
```ps
130-
Disconnect-Graph
131-
```
102+
## License
132103

133-
## Troubleshooting Permission Related Errors
104+
Copyright (c) Microsoft Corporation. All Rights Reserved. Licensed under the MIT [license](LICENSE.txt).
134105

135-
When working with various operations in the Graph, you may encounter an error such as "Insufficient privileges to complete the operation." For example, this particular error can occur when using the `New-Application` command if the appropriate permissions are not granted.
106+
<!-- References -->
136107

137-
If permission related errors occur and the user you authenticated with in the popup has the appropriate permissions to perform the operation try these steps.
108+
<!-- Shields -->
109+
[Mg]: https://img.shields.io/powershellgallery/v/Microsoft.Graph.svg?style=flat-square&label=Microsoft.Graph
138110

139-
- You can try running `Disconnect-Graph`, then `Connect-Graph`. Then, run the code that encountered the permission issues to see if it works.
140-
- You can try running `Connect-Graph -ForceRefresh`. This will trigger a refresh of the access token in your cache. MSAL will only refresh the access token in your cache if it has expired (usually an hour), or if you explicitly refresh it via `-ForceRefresh`. Then, run the code that encountered the permission issues to see if it works.
111+
<!-- PS Gallery -->
112+
[MgGallery]: https://www.powershellgallery.com/packages/Microsoft.Graph/

0 commit comments

Comments
 (0)