Skip to content

Commit 5c71cc5

Browse files
peombwapeombwa
committed
Move generation steps to wiki.
1 parent 3d31022 commit 5c71cc5

File tree

1 file changed

+48
-97
lines changed

1 file changed

+48
-97
lines changed

‎README.md‎

Lines changed: 48 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,89 @@
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

44
## Installing the Microsoft.Graph Module
55

6-
The modules are now published on the PowerShell Gallery. Installing is as simple as:
6+
All the modules are published on [PowerShell Gallery](https://www.powershellgallery.com/packages/Microsoft.Graph). Installing is as simple as:
77

88
```ps
9-
Install-module Microsoft.Graph
9+
Install-Module Microsoft.Graph
1010
```
1111

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.
13-
14-
## Generate Module
15-
16-
### Prerequisite
17-
18-
1. [Download](https://github.com/PowerShell/PowerShell/releases/tag/v6.2.3) and install PowerShell Core.
19-
20-
2. Install AutoRest.
21-
22-
```ps
23-
npm install -g "@autorest/autorest"
24-
```
25-
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.
28-
29-
***N.B - Once we have a preview version of the modules in PowerShell Gallery, this step won't be needed.***
30-
31-
### Generation Steps
32-
33-
1. Clone the [msgraph-sdk-powershell](https://github.com/microsoftgraph/msgraph-sdk-powershell) repo locally.
34-
35-
```ps
36-
git clone https://github.com/microsoftgraph/msgraph-sdk-powershell.git -b dev
37-
```
38-
39-
2. Generate, pack and optionally publish `Microsoft.Graph.Authentication` module.
40-
41-
```ps
42-
. \msgraph-sdk-powershell\tools\GenerateAuthenticationModule.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
43-
```
44-
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:
50-
51-
```ps
52-
. \msgraph-sdk-powershell\tools\GenerateModules.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
53-
```
54-
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.
63-
64-
```ps
65-
. \msgraph-sdk-powershell\tools\GenerateRollUpModule.ps1 -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ModuleVersion {ModuleVersion} -Publish
66-
```
67-
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.
73-
74-
```ps
75-
. \msgraph-sdk-powershell\tools\PublishModule.ps1 -Modules "Graph", "Authentication", "Subscriptions", "Teams" -RepositoryName {RepositoryName} -RepositoryApiKey {APIKey} -ArtifactsLocation {ArtifactsLocation}
76-
```
12+
If you are upgrading from our preview modules, run `Install-Module` with AllowClobber and Force parameter to avoid command name conflicts:
13+
```ps
14+
Install-Module Microsoft.Graph -AllowClobber -Force
15+
```
7716

78-
#### Common Generation Scripts Parameters
17+
Given the large size of the API surface area, one can also install only the service module(s) they are interested in:
18+
```ps
19+
Install-Module Microsoft.Graph.Users
20+
```
21+
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.
7922

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.
23+
## Usage
8424

85-
## Run Generated Modules
25+
1. Authentication
26+
27+
The SDK supports two types of authentication: delegated access, and app-oly access.
28+
- Delegated access via Device Code Flow.
8629

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:
30+
```ps
31+
Connect-Graph -Scopes "User.Read.All", "Group.ReadWrite.All"
32+
```
8833
89-
```ps
90-
Install-Module Microsoft.Graph -Repository {RepositoryName} # v1.0 modules
91-
or
92-
Install-Module Microsoft.Graph.Beta -Repository {RepositoryName} # beta modules
93-
```
34+
- App only access via Client Credential with a certificate.
9435
95-
2. Authenticate to Microsoft Identity to get an access token to call Microsoft Graph modules.
96-
- Delegated access via Device Code Flow.
36+
The certificate will be loaded from `Cert:\CurrentUser\My\` store. Ensure the certificate is present in the store before calling `Connect-Graph`.
37+
38+
You can pass either `-CertificateThumbprint` or `-CertificateName` to `Connect-Graph`.
9739
9840
```ps
99-
Connect-Graph -Scopes "User.Read.All"
41+
# Using -CertificateThumbprint
42+
Connect-Graph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateThumbprint "YOUR_CERT_THUMBPRINT"
10043
```
10144
102-
- App only access via Client Credential Flow with a certificate.
45+
or
10346
10447
```ps
105-
# Replace CN=DaemonConsoleCert with your certificate name.
106-
Connect-Graph -ClientId ClientId -TenantId TenantId -CertificateName "CN=DaemonConsoleCert"
48+
# Using -CertificateName
49+
Connect-Graph -ClientId "YOUR_APP_ID" -TenantId "YOUR_TENANT_ID" -CertificateName "YOUR_CERT_SUBJECT"
10750
```
10851
109-
3. Call `Get-User` command.
52+
2. List users in your tenant.
11053
11154
```ps
112-
# Authenticate for delegated access.
113-
Connect-Graph
114-
115-
Get-User -Top 10 -Select Id, DisplayName, BusinessPhones | Format-Table Id, DisplayName, BusinessPhones
55+
Get-User -Top 10 -Property Id, DisplayName, BusinessPhones | Format-Table Id, DisplayName, BusinessPhones
11656
```
11757
118-
4. Call `Get-UserMessage` cmdlet.
58+
3. Filter a user in your tenant.
11959
12060
```ps
121-
# Authenticate for app only access.
122-
Connect-Graph -ClientId ClientId -TenantId TenantId -CertificateName CertificateName
61+
$user = Get-MgUser -Filter "displayName eq 'Megan Bowen'"
62+
```
63+
64+
4. Create a new app registration.
12365
124-
Get-UserMessage -UserId UserId -Top 10 -Skip 10 -Select Id, Subject, CreatedDateTime | Format-Table CreatedDateTime, Subject, Id
66+
```ps
67+
New-MgApplication -DisplayName "ScriptedGraphPSApp" `
68+
-SignInAudience "AzureADMyOrg" `
69+
-Web @{ RedirectUris = "https://localhost"}
12570
```
12671
127-
5. Sign out of the current logged in context i.e. app only or delegated access.
72+
5. Sign out of the current logged-in context i.e. app only or delegated access.
12873
12974
```ps
13075
Disconnect-Graph
13176
```
77+
## API Version
78+
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.
79+
80+
```ps
81+
Select-MgProfile -Name "beta"
82+
```
13283

13384
## Troubleshooting Permission Related Errors
13485

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.
86+
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.
13687

13788
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.
13889

0 commit comments

Comments
 (0)