Include steps in the readme on how to configure the environment
This commit is contained in:
Родитель
c8283280e4
Коммит
2460c27bf7
87
README.md
87
README.md
|
@ -1,20 +1,21 @@
|
||||||
# Table of Contents
|
# Table of Contents
|
||||||
- [Table of Contents](#table-of-contents)
|
- [Table of Contents](#Table-of-Contents)
|
||||||
- [Intune-PowerShell-SDK](#intune-powershell-sdk)
|
- [Intune-PowerShell-SDK](#Intune-PowerShell-SDK)
|
||||||
- [Getting started](#getting-started)
|
- [Getting started](#Getting-started)
|
||||||
- [One-time setup (PowerShell Gallery)](#one-time-setup-powershell-gallery)
|
- [One-time setup (PowerShell Gallery)](#One-time-setup-PowerShell-Gallery)
|
||||||
- [One-time setup (GitHub)](#one-time-setup-github)
|
- [One-time setup (GitHub)](#One-time-setup-GitHub)
|
||||||
- [Before this module is used in your organization](#before-this-module-is-used-in-your-organization)
|
- [Before this module is used in your organization](#Before-this-module-is-used-in-your-organization)
|
||||||
- [Each time you use the module](#each-time-you-use-the-module)
|
- [Each time you use the module](#Each-time-you-use-the-module)
|
||||||
- [Discovering available commands](#discovering-available-commands)
|
- [Discovering available commands](#Discovering-available-commands)
|
||||||
- [Example usage](#example-usage)
|
- [Example usage](#Example-usage)
|
||||||
- [Retrieving objects](#retrieving-objects)
|
- [Retrieving objects](#Retrieving-objects)
|
||||||
- [Creating objects](#creating-objects)
|
- [Creating objects](#Creating-objects)
|
||||||
- [Modifying objects](#modifying-objects)
|
- [Modifying objects](#Modifying-objects)
|
||||||
- [Deleting objects](#deleting-objects)
|
- [Deleting objects](#Deleting-objects)
|
||||||
- [Calling functions and actions](#calling-functions-and-actions)
|
- [Calling functions and actions](#Calling-functions-and-actions)
|
||||||
- [Notable features](#notable-features)
|
- [Tips and Tricks](#Tips-and-Tricks)
|
||||||
- [Known issues and workarounds](#known-issues-and-workarounds)
|
- [Notable features](#Notable-features)
|
||||||
|
- [Known issues and workarounds](#Known-issues-and-workarounds)
|
||||||
|
|
||||||
# Intune-PowerShell-SDK
|
# Intune-PowerShell-SDK
|
||||||
This repository contains the source code for the PowerShell module which provides support for the Intune API through Microsoft Graph.
|
This repository contains the source code for the PowerShell module which provides support for the Intune API through Microsoft Graph.
|
||||||
|
@ -31,31 +32,55 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Install-Module -Name Microsoft.Graph.Intune
|
Install-Module -Name Microsoft.Graph.Intune
|
||||||
```
|
```
|
||||||
|
|
||||||
## One-time setup (GitHub)
|
## One-time setup (GitHub)
|
||||||
1. Download the module from the [Releases](https://github.com/Microsoft/Intune-PowerShell-SDK/releases) tab in the GitHub repository.
|
1. Download the module from the [Releases](https://github.com/Microsoft/Intune-PowerShell-SDK/releases) tab in the GitHub repository.
|
||||||
2. The "drop\outputs\build\Release\net471" folder in the zip file contains the module.
|
2. The "drop\outputs\build\Release\net471" folder in the zip file contains the module.
|
||||||
- If you are using Windows, extract the "net471" folder. **You must have .NET 4.7.1 or higher installed**.
|
- If you are using Windows, extract the "net471" folder. **You must have .NET 4.7.1 or higher installed**.
|
||||||
3. The module manifest is the "Microsoft.Graph.Intune.psd1" file inside this folder. This is the file you would refer to when importing the module.
|
3. The module manifest is the "Microsoft.Graph.Intune.psd1" file inside this folder. This is the file you would refer to when importing the module.
|
||||||
4. Import the module:
|
4. Import the module:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Import-Module $sdkDir/Microsoft.Graph.Intune.psd1
|
Import-Module $sdkDir/Microsoft.Graph.Intune.psd1
|
||||||
```
|
```
|
||||||
|
|
||||||
## Before this module is used in your organization
|
## Before this module is used in your organization
|
||||||
An admin user must provide consent for this app to be used in their organization. This can be done with the following command:
|
An admin user must provide consent for this app to be used in their organization. This can be done with the following command:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Connect-MSGraph -AdminConsent
|
Connect-MSGraph -AdminConsent
|
||||||
```
|
```
|
||||||
|
|
||||||
## Each time you use the module
|
## Each time you use the module
|
||||||
To authenticate with Microsoft Graph (this is not required when using CloudShell):
|
To authenticate with Microsoft Graph (this is not required when using CloudShell):
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Connect-MSGraph
|
Connect-MSGraph
|
||||||
```
|
```
|
||||||
To authenticate with Microsoft Graph using [System.Management.Automation.PSCredential]
|
|
||||||
|
To authenticate with Microsoft Graph using a [PSCredential] object:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
$adminUPN=Read-Host -Prompt "Enter UPN"
|
# 1. Create the PSCredential object
|
||||||
$adminPwd=Read-Host -AsSecureString -Prompt "Enter password for $adminUPN"
|
$adminUPN = Read-Host -Prompt "Enter UPN"
|
||||||
$creds = New-Object System.Management.Automation.PSCredential ($AdminUPN, $adminPwd)
|
$adminPwd = Read-Host -AsSecureString -Prompt "Enter password for $adminUPN"
|
||||||
$connection = Connect-MSGraph -PSCredential $creds
|
$creds = New-Object System.Management.Automation.PSCredential ($adminUPN, $adminPwd)
|
||||||
|
|
||||||
|
# 2. Log in with these credentials
|
||||||
|
Connect-MSGraph -PSCredential $creds
|
||||||
|
```
|
||||||
|
|
||||||
|
To authenticate in a non-standard environment:
|
||||||
|
```PowerShell
|
||||||
|
# 1. Setup the environment
|
||||||
|
# For example, in a National Cloud environment, the following is required before logging in
|
||||||
|
Update-MSGraphEnvironment -AuthUrl 'https://login.microsoftonline.us/common' -GraphBaseUrl 'https://graph.microsoft.us' -GraphResourceId 'https://graph.microsoft.us' -SchemaVersion 'beta'
|
||||||
|
|
||||||
|
# 2. Log in
|
||||||
|
Connect-MSGraph
|
||||||
|
|
||||||
|
# 3. Use the cmdlets
|
||||||
|
# NOTE: If the schema version has been changed to something other than "v1.0" as in the above
|
||||||
|
# "Update-MSGraphEnvironment" command, only "Invoke-MSGraphRequest" should be used to make calls,
|
||||||
|
# because the standard cmdlets (e.g. "Get-IntuneMobileApp") have been generated based on the
|
||||||
|
# "v1.0" schema, and can produce unexpected results when used with other schema versions
|
||||||
|
Invoke-MSGraphRequest -HttpMethod GET -Url 'deviceAppManagement/mobileApps'
|
||||||
```
|
```
|
||||||
|
|
||||||
## Discovering available commands
|
## Discovering available commands
|
||||||
|
@ -63,10 +88,12 @@ Get the full list of available cmdlets:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Get-Command -Module Microsoft.Graph.Intune
|
Get-Command -Module Microsoft.Graph.Intune
|
||||||
```
|
```
|
||||||
|
|
||||||
Get documentation on a particular cmdlet:
|
Get documentation on a particular cmdlet:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Get-Help <cmdlet name>
|
Get-Help <cmdlet name>
|
||||||
```
|
```
|
||||||
|
|
||||||
Use a UI to see the parameter sets more easily:
|
Use a UI to see the parameter sets more easily:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Show-Command <cmdlet name>
|
Show-Command <cmdlet name>
|
||||||
|
@ -78,14 +105,17 @@ Get all Intune applications:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Get-IntuneMobileApp
|
Get-IntuneMobileApp
|
||||||
```
|
```
|
||||||
|
|
||||||
Get all Intune device configurations:
|
Get all Intune device configurations:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Get-IntuneDeviceConfigurationPolicy
|
Get-IntuneDeviceConfigurationPolicy
|
||||||
```
|
```
|
||||||
|
|
||||||
Get all Intune managed devices:
|
Get all Intune managed devices:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Get-IntuneManagedDevice
|
Get-IntuneManagedDevice
|
||||||
```
|
```
|
||||||
|
|
||||||
Get a filtered list of applications and select only the "displayName" and "publisher" properties:
|
Get a filtered list of applications and select only the "displayName" and "publisher" properties:
|
||||||
```PowerShell
|
```PowerShell
|
||||||
# The filter string follows the same rules as specified in the OData v4.0 specification.
|
# The filter string follows the same rules as specified in the OData v4.0 specification.
|
||||||
|
@ -122,6 +152,11 @@ $deviceToLock = $allDevices[0]
|
||||||
$deviceToLock | Invoke-IntuneManagedDeviceRemoteLock
|
$deviceToLock | Invoke-IntuneManagedDeviceRemoteLock
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Tips and Tricks
|
||||||
|
- Create TimeSpan objects using the [New-TimeSpan](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-timespan?view=powershell-6) cmdlet
|
||||||
|
- Create DateTime or DateTimeOffset objects using the [Get-Date](https://docs.microsoft.com/en-us/powershell/module/Microsoft.PowerShell.Utility/Get-Date?view=powershell-6) cmdlet
|
||||||
|
- If a parameter accepts an "Object" rather than a more specific type, use the documentation to identify what type of object it requires. For example, if the documentation says that a parameter represents a property of type "microsoft.graph.mobileApp" or "microsoft.graph.deviceConfiguration", use the "New-MobileAppObject" or "New-DeviceConfigurationObject" cmdlets to create the respective objects.
|
||||||
|
|
||||||
# Notable features
|
# Notable features
|
||||||
- Standard PowerShell objects are used for input/output, meaning that all built-in PowerShell features/utilities/tricks work, including:
|
- Standard PowerShell objects are used for input/output, meaning that all built-in PowerShell features/utilities/tricks work, including:
|
||||||
- Piping of objects between cmdlets
|
- Piping of objects between cmdlets
|
||||||
|
@ -141,10 +176,12 @@ $deviceToLock | Invoke-IntuneManagedDeviceRemoteLock
|
||||||
|
|
||||||
# Known issues and workarounds
|
# Known issues and workarounds
|
||||||
- Importing the `MSOnline` cmdlets before importing this `Intune` module will cause errors. Please use the `AzureAD` module instead, as the `MSOnline` module is deprecated.
|
- Importing the `MSOnline` cmdlets before importing this `Intune` module will cause errors. Please use the `AzureAD` module instead, as the `MSOnline` module is deprecated.
|
||||||
- If you absolutely must use the `MSOnline` module, it should be imported AFTER the `Intune` module. Note, however, that this is not officially supported.
|
- If you absolutely must use the `MSOnline` module, it should be imported AFTER the `Intune` module. Note, however, that this is not officially supported.
|
||||||
- If downloaded from Github, the file "Microsoft.Intune.PowerShellGraphSDK.dll" may be blocked when a release is first downloaded. This will stop the assembly from correctly loading (and you will see an error message if you try to import the module).
|
- If downloaded from Github, the file "Microsoft.Intune.PowerShellGraphSDK.dll" may be blocked when a release is first downloaded. This will stop the assembly from correctly loading (and you will see an error message if you try to import the module).
|
||||||
```PowerShell
|
```PowerShell
|
||||||
Dir -Recurse $sdkDir | Unblock-File
|
Dir -Recurse $sdkDir | Unblock-File
|
||||||
```
|
```
|
||||||
- The SDK is built out of Microsoft Graph v1.0 release, some functionality available in the Intune Administration UI is built using the Microsoft Graph beta release.
|
- Cmdlets in this module are generated based on the "v1.0" version of the Graph schema. In order to access functionality in the "beta" schema you must change the schema version using the command below. However, note that only the `Invoke-MSGraphRequest` cmdlet should be used to make calls to Graph. This is because the difference in entities/properties between "beta" and "v1.0" (the schema that most cmdlets were generated from) can result in unexpected behavior.
|
||||||
- Workaround is to use Invoke-RestMethod for such functionality. For more details see: https://github.com/Microsoft/Intune-PowerShell-SDK/issues/14
|
```PowerShell
|
||||||
|
Update-MSGraphEnvironment -SchemaVersion 'beta'
|
||||||
|
```
|
||||||
|
|
Загрузка…
Ссылка в новой задаче