{"id":12522,"date":"2022-12-21T05:20:20","date_gmt":"2022-12-21T13:20:20","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/?p=12522"},"modified":"2023-01-04T10:18:22","modified_gmt":"2023-01-04T18:18:22","slug":"microsoft-graph-powershell-v2-is-now-in-public-preview-half-the-size-and-will-speed-up-your-automations","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/microsoft-graph-powershell-v2-is-now-in-public-preview-half-the-size-and-will-speed-up-your-automations\/","title":{"rendered":"Microsoft Graph PowerShell v2 is now in public preview, half the size and speeds up automation"},"content":{"rendered":"

Automate and manage your Microsoft 365 tenant by using the Microsoft Graph PowerShell SDK that brings the Microsoft Graph API to PowerShell. Focus on what really matters and build scripts to automate your work instead of worrying about throttling, retries, redirects, and authentication. The Microsoft Graph PowerShell SDK handles all of that and provides PowerShell cmdlets for all REST APIs available in Microsoft Graph.<\/p>\n

Today, we are announcing the public preview of Microsoft Graph PowerShell SDK v2 that includes features to enhance your experience. Read on for details.<\/p>\n

Write more robust, less error-prone, and less ambiguous scripts<\/span><\/h2>\n

To help you write more robust scripts, the v1.0 and beta modules will use different prefixes in their cmdlets.<\/p>\n

Users should always rely on Microsoft Graph v1.0 when writing scripts. However, sometimes there is a need to use the beta endpoint for testing or early adoption before a feature is available in v1.0. The Microsoft Graph beta endpoint and any functionality there is still in preview status and can change. This makes the beta endpoints unreliable for production usage since it may break existing scenarios without notice. So, thinking of that, you will now be able to easily combine both production and preview in any script you might need, using v1.0 as much as possible and beta only where you truly need. Using prefixes will also help you identify where you are using preview functionalities.<\/p>\n

Thus, the v1.0 module will continue to use the same naming as the current v1 version to avoid breaking changes for those running their script against Microsoft Graph v1.0.\u00a0 Changes will only be observed for beta. Here is an example.<\/p>\n\n\n\n\n\n\n
<\/td>\nMicrosoft Graph API v1.0 endpoint<\/strong><\/td>\nMicrosoft Graph API Beta endpoint<\/strong><\/td>\n<\/tr>\n
Module Names<\/strong><\/td>\nMicrosoft.Graph<\/td>\nMicrosoft.Graph.Beta<\/strong><\/td>\n<\/tr>\n
Command Names<\/strong><\/td>\nGet-MgUser<\/td>\nGet-MgBeta<\/strong>User<\/td>\n<\/tr>\n
Entity Namespace<\/strong><\/td>\nMicrosoft.Graph.PowerShell.Models.Users<\/td>\nMicrosoft.Graph.Beta<\/strong>.PowerShell.Models.Users<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

Consider a scenario where users were mixing v1.0 and beta commands, a situation where almost everything needed is available in Microsoft Graph v1 endpoint and only a couple of preview APIs that are only available in beta. With the Microsoft Graph PowerShell SDK v1, we had the following:<\/p>\n

Connect-MgGraph\r\nSelect-MgProfile v1.0\r\n$V1Users = Get-MgUser\r\nSelect-MgProfile beta\r\n$BetaDriveActivity = Get-MgDriveActivity<\/code><\/pre>\n
As you can see above, it is quite easy to miss in the middle of a script that cmdlets are using Microsoft Graph beta APIs. With Microsoft Graph PowerShell v2, keeping in mind to have both modules installed, users can accomplish the same result with the following:<\/p>\n
Connect-MgGraph\r\n$V1Users = Get-MgUser\r\n$BetaDriveActivity = Get-MgBetaDriveActivity\r\n<\/code><\/pre>\n
 <\/p>\n
Speed up your automations<\/span><\/h2>\n
With the SDK now 58% smaller, you can choose the module which better suits your needs with the new Microsoft Graph PowerShell v2. The first option, Microsoft.Graph<\/strong> module that targets https:\/\/graph.microsoft.com\/v1.0\/<\/a> and it is the home for those who only want to work with stables APIs. The second one, Microsoft.Graph.Beta<\/strong> that targets https:\/\/graph.microsoft.com\/beta<\/a>, which is where you will hit APIs we are still working on and in preview.<\/p>\n
You can optimize your scripts even further by installing only <\/span>the specific modules your scripts will use rather than the entire SDK.<\/p>\n
Install-Module Microsoft.Graph.Users\r\nConnect-MgGraph\r\n$V1Users = Get-MgUser<\/code><\/pre>\n
PowerShell users will have access to smaller packages that facilitate its management and significantly speed up installation of the SDK, benefiting, but not limited to, CI\/CD pipelines and automation on Azure. The installation size of the SDK is reduced by up to 58% in case of using the module targeting Microsoft Graph v1 endpoint.<\/p>\n\n\n\n\n\n\n
Version of Microsoft Graph PS SDK<\/strong><\/td>\nPackage Size<\/strong><\/td>\nInstall Size<\/strong><\/td>\n<\/tr>\n
Microsoft.Graph V1.19.0<\/td>\n147.57 MB<\/td>\n855.81 MB<\/td>\n<\/tr>\n
Microsoft.Graph V2-preview<\/td>\n64.97 MB (-55.97%)<\/td>\n351.31 MB (-58.95%)<\/td>\n<\/tr>\n
Microsoft.Graph.Beta V2-preview<\/td>\n112.72 MB (-23.63%)<\/td>\n651.31 MB (-23.89%)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
 <\/p>\n
New authentication methods for more scenarios<\/h2>\n
New authentication flows are available for you to decided which ones satisfy your demands.<\/p>\n
1. Managed Identity<\/h3>\n
A common challenge when writing automation scripts is the management of secrets, credentials, certificates, and keys used to secure communication between services. Eliminate the need to manage credentials by allowing the module to obtain access tokens for Azure resources that are protected by Azure Active Directory. The identity is managed by the Azure platform and does not require you to provision or rotate any secrets. See Managed Identities from Azure resources<\/a> for more details.<\/p>\n
a. System-assigned managed identity<\/h4>\n
Uses an automatically managed identity on a service instance. The identity is tied to the lifecycle of a service instance.<\/p>\n
Connect-MgGraph -Identity<\/code><\/pre>\n
b. User-assigned managed identity<\/h4>\n
Uses a user created managed identity as a standalone Azure resource.<\/p>\n
Connect-MgGraph -Identity -ClientId \"User_Assigned_Managed_identity_Client_Id\"<\/code><\/pre>\n
2. Client Secret Credentials<\/h3>\n
If you need interactions in the background, without a user to sign in, this type of grant will help you. Support for client secret credentials was added by adding -ClientSecretCredential<\/strong> parameter to Connect-MgGraph<\/strong>. See Get-Credential<\/a> on how to get or create credentials.<\/p>\n
$ClientCredential = Get-Credential -Username \"Client_Id\"\r\n# Or create a credential object that is identical to the object that Get-Credential returns without prompting the user. This method requires a plain text password, which might violate the security standards in some enterprises. l\r\n# $ClientSecretCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $ApplicationId, $SecuredPassword\r\n# Enter client_secret in the password prompt.\r\nConnect-MgGraph -TenantId \"Tenant_Id\" -ClientSecretCredential $ClientCredential\r\n<\/code><\/pre>\n
3. Environment Variables Based Auth<\/h3>\n
Environment variables store the parameter keys and values, which then serve as input to your script and can help to not leaky information when sharing them with others. Now use -EnvironmentVariable<\/strong> to Connect-MgGraph<\/strong> to support environment variable based auth. It is important to notice that an error will be thrown if username and password are used to authenticate as this is not supported by design and that client secret takes precedence over certificate, i.e., if values for a client secret and certificate are both present, the client secret will be used. See Azure.Identity Environment Variables<\/a> for more details.<\/p>\n
# Add environment variables to be used by Connect-MgGraph.\r\n$Env:AZURE_CLIENT_ID = \"application id of the client app\"\r\n$Env:AZURE_TENANT_ID = \"Id of your tenant\"\r\n$Env:AZURE_CLIENT_SECRET = \"secret of the client app\"\r\n\r\n# Tell Connect-MgGraph to use your environment variables.\r\nConnect-MgGraph \u2013EnvironmentVariable\r\n<\/code><\/pre>\n
4. Certificate Credentials<\/h3>\n
Having a certificate only in the current user certificate store is no longer a limitation if you are using Microsoft Graph PowerShell SDK v2; the support to lookup for certificates in both current user and local machine certificate store were added. Priority will be given certificates in current user store if two identical certificates are present in both places.<\/p>\n
Connect-MgGraph -ClientId \"Client_Id\" -Tenant \"Tenant\" -CertificateThumbprint \"Cert_Thumbprint\"<\/code><\/pre>\n
Along with all the new ways of authentication, -ForceRefresh<\/strong> is no longer supported by the auth token credentials used in v2. Customers should instead use Disconnect-MgGraph<\/strong> to sign out of current context then call Connect-MgGraph<\/strong> to get a new access token. Also, to keep you even safer, we have changed -AccessToken<\/strong> from String to SecureString<\/strong> type.<\/p>\n
 <\/p>\n
Better performance<\/h2>\n
The HTTP\/2 protocol<\/a> focuses on improving performance and perceived latency by adding support for multiplexing, header compression, and server push. Users will now benefit from improved performance whenever HTTP\/2 is available, and the SDK will gracefully fall back to HTTP\/1.1 when HTTP\/2 is not supported by the API<\/p>\n
 <\/p>\n
Unblock scenarios with the new success range code support<\/h2>\n
Situations where the API was returning a different status code than what was documented in the API will no longer impact users. With success status code range support (2xx), new scenarios were unblocked by allowing all 2xx responses be treated as successful requests, making possible to get information from the response body when its available to use further in the script.<\/p>\n
Invoke-MgInstantiateApplicationTemplate -ApplicationTemplateId $applicationTemplateId -BodyParameter $params<\/code><\/pre>\n
Output:<\/p>\n
DEBUG: ============================ HTTP RESPONSE ============================\r\n\r\nStatus Code:\r\nCreated\r\n\r\nHeaders:\r\nCache-Control                 : no-cache\r\nTransfer-Encoding             : chunked\r\nLocation                      : https:\/\/graph.microsoft.com\/\r\nVary                          : Accept-Encoding\r\nStrict-Transport-Security     : max-age=31536000\r\nrequest-id                    : request-id\r\nclient-request-id             : client-request-id\r\nx-ms-ags-diagnostic           : {\"ServerInfo\":{\"DataCenter\":\"Brazil South\",\"Slice\":\"E\",\"Ring\":\"3\",\"ScaleUnit\":\"000\",\"RoleInstance\":\"CP1PEPF00002F02\"}}\r\nOData-Version                 : 4.0\r\nDate                          : Fri, 16 Dec 2022 19:22:27 GMT\r\n\r\nBody:\r\n{\r\n  \"@odata.context\": \"https:\/\/graph.microsoft.com\/v1.0\/$metadata#microsoft.graph.applicationServicePrincipal\",\r\n  \"application\": {\r\n    \"id\": \"id\",\r\n    \"appId\": \"app-id\",\r\n    \"applicationTemplateId\": \"application-template-id\",\r\n    \"createdDateTime\": \"2022-12-16T19:22:26Z\",\r\n    \"deletedDateTime\": null,\r\n    \"displayName\": \"Azure AD SAML Toolkit\",\r\n    \"description\": null,\r\n    \"groupMembershipClaims\": null,\r\n    \"identifierUris\": [],\r\n    \"isFallbackPublicClient\": false,\r\n  },\r\n  \"servicePrincipal\": {\r\n    \"id\": \"id\",\r\n    \"deletedDateTime\": null,\r\n    \"accountEnabled\": true,\r\n    \"appId\": \"app-id\",\r\n    \"applicationTemplateId\": \"application-template-id\",\r\n    \"appDisplayName\": \"Azure AD SAML Toolkit\",\r\n    \"alternativeNames\": [],\r\n    \"appOwnerOrganizationId\": \"app-owner-organization-id\",\r\n    \"displayName\": \"Azure AD SAML Toolkit\",\r\n    \"servicePrincipalNames\": [\r\n      \"\"\r\n    ],\r\n    \"servicePrincipalType\": \"Application\",\r\n    \"tags\": [\r\n      \"WindowsAzureActiveDirectoryIntegratedApp\"\r\n    ],\r\n    \"tokenEncryptionKeyId\": null,\r\n    \"samlSingleSignOnSettings\": null,\r\n    \"addIns\": [],\r\n    }\r\n  }\r\n}\r\n<\/code><\/pre>\n
NOTE: The response object shown here is shortened for readability.<\/p>\n
 <\/p>\n
Migration tool for scripts<\/h2>\n
A migration tool<\/a> will be provided to help customers migrate their scripts from using Microsoft Graph PowerShell SDK v1 to v2. The tool will be available when v2 reaches general availability. Customers can contact us on GitHub<\/a> and send any script they are willing to share to help us test and verify the tool.<\/p>\n
Try out the new version today!<\/h2>\n
Try out the new version<\/a> and let us know what you think on GitHub<\/a>! For questions about the Microsoft Graph API, go to Microsoft Q&A<\/a>.<\/p>\n
Next steps<\/h2>\n
Check out https:\/\/aka.ms\/graph\/sdk\/powershell\/upgrade-to-v2<\/a> to access a detailed document that outlines any breaking changes, fixes and will guide you through the migration that an SDK user might run while upgrading to v2 as well as provide examples for implementing the new features, helping you quickly take advantage of all the new capabilities.<\/p>\n
Add the new SDK for Microsoft Graph v1.0 module to your project. You can have a side-by-side installation by running the following command in the Package Manager Console or replace the Microsoft Graph PowerShell SDK installed by removing -AllowClobber:<\/p>\n
Install-Module Microsoft.Graph -AllowPrerelease -AllowClobber -Force<\/code><\/pre>\n
Or for Microsoft Graph beta module:<\/p>\n
Install-Module Microsoft.Graph.Beta -AllowPrerelease -AllowClobber -Force\r\n<\/code><\/pre>\n
Get started with the Microsoft Graph API<\/h2>\n
Microsoft Graph<\/a> is a single REST API that unifies data across many Microsoft services under one single endpoint.<\/strong> The API is a powerful tool for building applications that work with data from Microsoft 365 and other Microsoft services.<\/p>\n
Learn about Microsoft Graph SDKs<\/h2>\n
The SDK includes a set of tools, libraries, and documentation that make it easy to get started building applications that take advantage of the rich data and insights available through Microsoft Graph API.<\/p>\n
Start saving time and removing complexity in your code today. Sign up for the Microsoft 365 Developer Program<\/a> to get a free Microsoft 365 developer subscription and start using PowerShell to connect to Microsoft Graph<\/a>. We also recommend that you join our Microsoft 365 Platform community<\/a> calls and events, and get involved with other developers who use Microsoft Graph and build solutions for Microsoft 365.<\/p>\n
Here are some resources we have pulled together to help you get started.<\/p>\n
    \n
  1. Explore our public documentation<\/a>, where you can find how to install the SDK, authenticate, discover which API a cmdlet is calling and more.<\/li>\n
  2. Walk through the learning module<\/a>.<\/li>\n
  3. Use the Microsoft Graph Explorer<\/a>, a tool that lets you make requests and see responses against the Microsoft Graph, and which displays corresponding snippets to requests you make.<\/li>\n
  4. Visit our Microsoft Graph Dev Center<\/a>.<\/li>\n<\/ol>\n
    Thank you!<\/h2>\n
    We would like to thank all the members of the community who have helped us make this release better by reporting issues in GitHub<\/a>! Keep them coming!<\/p>\n
    Follow us on Twitter @Microsoft365Dev<\/a> for the latest announcements and resources!<\/p>\n","protected":false},"excerpt":{"rendered":"
    Automate and manage your Microsoft 365 tenant by using the Microsoft Graph PowerShell SDK v2 that brings the Microsoft Graph API to PowerShell. The SDK v2 is now in public preview.<\/p>\n","protected":false},"author":69077,"featured_media":12536,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[3],"tags":[149],"class_list":["post-12522","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-graph","tag-microsoft-graph-powershell-sdk"],"acf":[],"blog_post_summary":"
    Automate and manage your Microsoft 365 tenant by using the Microsoft Graph PowerShell SDK v2 that brings the Microsoft Graph API to PowerShell. The SDK v2 is now in public preview.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/12522","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/69077"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=12522"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/12522\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/12536"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=12522"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=12522"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=12522"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}