PowerShell을 사용 하 여 작업 공간 분석 라이선스 할당Assign Workplace Analytics licenses with PowerShell

Azure Active Directory (Azure AD)에서 PowerShell을 사용 하 여 작업 공간 분석 라이선스를 할당 하려면 다음 단계를 수행 합니다.Use the following steps to assign Workplace Analytics licenses with PowerShell in Azure Active Directory (Azure AD).

설치 필수 구성 요소Installation prerequisites

  1. 다음 단계를 수행 하 여 Azure AD PowerShell 모듈을 설치 합니다.Install the Azure AD PowerShell module by following these steps:

    a) 상승 된 Windows PowerShell 명령 프롬프트를 엽니다.a) Open an elevated Windows PowerShell command prompt.

    b) 다음 명령을 입력 합니다.b) Enter the following command:

    Install-Module *AzureAD*
    
  2. Azure AD PowerShell 모듈을 실행 합니다.Run the Azure AD PowerShell module:

    a) PowerShell을 시작 합니다.a) Start PowerShell.

    b) 다음 명령을 입력 합니다.b) Enter the following command:

    Import-Module *AzureAD*
    

라이선스 할당Assigning licenses

회사 분석은 유효한 작업 공간 분석 라이선스가 있는 사용자의 계정에서 데이터를 추출할 수만 있습니다.Workplace Analytics can only extract data from the accounts of users who have valid Workplace Analytics licenses.

  1. 사용자에 게 회사 분석 라이선스를 할당 하려면 다음을 수행 합니다.To assign a Workplace Analytics license to a user:

    PowerShell을 열고 다음 명령을 실행 하 여 가져오기 모듈을 시작 하 고 Azure AD에 로그인 합니다.With PowerShell open, start the Import Module, and log in to Azure AD by running the following commands:

    Import-Module *AzureAD*
    
    Connect-AzureAD
    

    로그인 하려면 관리자 권한이 있는 자격 증명이 필요 합니다.To log in, you need credentials with admin privileges.

    Azure Active Directory 로그인

  2. 다음 변수 데이터를 복사 하 여 PowerShell 명령줄에 붙여 넣은 다음 실행 합니다.Copy and paste the following variable data into the PowerShell command line, and then run it:

     $UserToLicense = Get-AzureADUser -SearchString '<usertolicense@domain.com>'
     $LicenseSku = Get-AzureADSubscribedSku | Where {$_.SkuPartNumber -eq 'WorkPlace_Analytics'}
     $License = New-Object -TypeName Microsoft.Open.AzureAD.Model.AssignedLicense
     $License.SkuId = $LicenseSku.SkuId
     $AssignedLicenses = New-Object -TypeName Microsoft.Open.AzureAD.Model.AssignedLicenses
    
  3. 라이선스를 할당 하려면 다음 코드를 복사 하 여 PowerShell 명령줄에 붙여 넣은 다음 실행 합니다.To assign a license, copy and paste the following code into the PowerShell command line, and then run it:

     $AssignedLicenses.AddLicenses = $License
     Set-AzureADUserLicense -ObjectId $UserToLicense.ObjectId -AssignedLicenses $AssignedLicenses
    
  4. 라이선스가 할당 되었는지 확인 하려면 다음 코드를 복사 하 여 PowerShell 명령줄에 붙여 넣은 다음 실행 합니다.To verify that the license is assigned, copy and paste the following code into the PowerShell command line, and then run it:

     Get-AzureADUserLicenseDetail -ObjectId $UserToLicense.ObjectId | Select -Expand ServicePlans | Where {$_.ServicePlanName -eq "Workplace_Analytics"}
    

    마지막 명령을 실행 한 후 명령줄에 항목이 표시 됩니다.After this last command runs, you'll see an entry on the command line. 그렇지 않은 경우 또는 오류 메시지가 표시 되 면 라이선스가 성공적으로 할당 되지 않은 것입니다.If not, or if an error message shows, the license was not successfully assigned.

테 넌 트에서 사용 가능한 라이선스 보기View Available licenses on your tenant

테 넌 트에 대 한 사용 가능한 라이선스를 보려면 PowerShell에서 다음을 실행 합니다.To view available licenses for your tenant and current usage run the following in PowerShell:

Connect-MsolService

이제 Office 365 테 넌 트에 연결 되었으므로 다음을 실행 합니다.Now that you're connected to the Office 365 tenant, run the following next:

Get-MsolAccountSku

Office 365 PowerShell을 통해 대량으로 작업 공간 분석 라이선스 추가Add Workplace Analytics licenses in bulk through Office 365 PowerShell

많은 수의 사용자에 게 작업 공간 분석 라이선스를 할당 해야 하는 경우이 섹션에서 제공 되는 Office 365 PowerShell 용 대량 라이선스 스크립트를 사용할 수 있습니다.If you need to assign Workplace Analytics licenses to a large number of users, you can use the bulk license script for Office 365 PowerShell provided in this section.

소프트웨어 요구 사항Software Requirements

회사 분석 대량 라이선스 스크립트는 Azure Active Directory PowerShell 모듈을 사용 하 여 테 넌 트 id에 필요한 라이선스 변경을 수행 합니다.The Workplace Analytics bulk license script uses the Azure Active Directory PowerShell module to make the necessary licensing changes to your tenant identities. Azure Active Directory PowerShell 모듈이 설치 되어 있는지 확인 하려면 다음을 수행 합니다.To ensure that the Azure Active Directory PowerShell module is installed:

  1. Windows PowerShell을 관리자 권한으로 열고 다음 명령을 실행 합니다.Open Windows PowerShell as an administrator and run the following command:

    Set-ExecutionPolicy RemoteSigned
    
  2. 확인 메시지가 표시 되 면 로컬 PowerShell 스크립트를 실행 하도록 허용 하기 위해 변경 내용을 적용 합니다.When a confirmation message appears, accept the change in order to allow local PowerShell scripts to run.

  3. 컴퓨터에서 실행 정책이 올바르게 설정 된 후에는 다음 cmdlet을 실행 합니다.After the execution policy is set correctly on the machine, run the following cmdlet:

     Install-Module -Name MSOnline -Repository PSGallery
    

Note

Cmdlet이 실행 되지 않으면 이전 버전의 WMF (Windows Management Framework)를 실행 하 고 있을 수 있습니다.If the cmdlet fails to execute, you might be running an older version of Windows Management Framework (WMF). 이 경우에는 MSI를 통해 필요한 로그인 도우미 및 Azure Active Directory PowerShell 모듈을 다운로드 하 여 설치 합니다.In that case, download and install the required sign-in assistant and the Azure Active Directory PowerShell module through MSI. 이러한 필수 패키지를 설치 하는 방법에 대 한 자세한 내용은 Connect To Office 365 PowerShell을 참조 하십시오.For instructions to install these required packages, see Connect to Office 365 PowerShell.

입력 요구 사항Input Requirements

작업 공간 분석 대량 라이선스 스크립트는 CSV 참조 파일을 입력으로 사용 합니다.The Workplace Analytics bulk license script uses a CSV reference file as input. 이 스크립트는 CSV 파일에 나열 된 각 주소를 참조 하 고 모든 사용자에 게 작업 공간 분석 라이선스를 할당 하려고 시도 합니다.The script references each address listed in the CSV file and attempts to assign Workplace Analytics license to all users.

이미 라이선스를 할당 받은 각 사용자는 현재의 모든 라이선스를 유지 합니다.Each user who is already assigned a license retains all current licensing. 새 사용자에 게는 작업 공간 분석 라이선스가 수신 됩니다.New users will receive a Workplace Analytics license. CSV 입력에는 모든 전자 메일 주소를 포함 하는 머리글이 "Email" 인 단일 열이 있어야 합니다.The CSV input must have a single column with the header "Email" that contains all email addresses.

입력 CSV 파일의 형식을 지정 하는 방법에 대 한 자세한 내용은 예제 CSV export file를 참조 하십시오.For more details on formatting the input CSV file, see example CSV export file.

스크립트 설명Script description

Add-WpALicense.ps1 스크립트는 CSV 전자 메일 주소 입력을 기반으로 Office 365 id에 작업 영역 분석 라이선스를 할당 하도록 디자인 되었습니다.The Add-WpALicense.ps1 script is designed to assign Workplace Analytics licenses to Office 365 identities based on CSV email address input. 전자 메일 주소 입력은 MSOL (Microsoft Online) 개체의 UserPrincipalNameProxyAddresses 특성에 따라 올바른 office 365 id를 식별 하는 데 사용 되며, office 365 id에 라이선스를 할당 하려고 합니다.The email address input is used to identify the correct Office 365 identity based on the UserPrincipalName and ProxyAddresses attributes of the MSOL (Microsoft Online) object, and then tries to assign a license to the Office 365 identity.

스크립트 실행Script Execution

  1. 아직 없는 경우 C:\Scripts 폴더를 만듭니다.Create a C:\Scripts folder if it does not already exist.

  2. 다음 스크립트를 복사 하 여 텍스트 편집기에 붙여넣고 스크립트를 C:\Scripts\Add-WpALicense.ps1저장 합니다.Copy the following script and paste it into a text editor, and then save the script as C:\Scripts\Add-WpALicense.ps1.

    <#
    .NOTES
     Title:    Add-WpALicense.ps1
     Date:     February 25th, 2020
     Version:  1.0.4
    .SYNOPSIS
     This script is designed to add Workplace Analytics licenses to a CSV list of email addresses that correlate to Office 365 identities.
    .DESCRIPTION
     Add-WpALicense is designed to assign Workplace Analytics licenses to Office 365 identities based on CSV e-mail address input. The e-mail address input will be used to identify the correct Office365 identity based on the UserPrincipalName and ProxyAddresses attributes of the MSOL object and try to assign a license to the identity.
    .PARAMETER CSV
     The CSV input file contains all of the email addresses that are given a license. Use Email as the header and when save the file with the UTF-8 encoded format.
    .PARAMETER LicenseSKU
     The WORKPLACE_ANALYTICS LicenseSKU will be applied to a user that's found. The script tries to automatically apply a license SKU. If a license SKU is provided, the script tries to match it with the domain. An example SKU is CONTOSO:WORKPLACE_ANALYTICS.
     .EXAMPLE
     .\Add-WpALicense.ps1 -CSV c:\users\user123\desktop\inputCSV -LicenseSku CONTOSO:WORKPLACE_ANALYTICS
    
     The script would ingest the CSV file from the specified location in this example and try to apply the MSOL license SKU of CONTOSO:WORKPLACE_ANALYTICS to all users that are found in the MSOL structure of the tenant.
        #>
        param
        (
        [parameter(Mandatory=$true,Position=0,HelpMessage="Please provide a CSV file that has the Email column header.")]
        [ValidateNotNullorEmpty()]
        [string]$CSV,
        [parameter(Mandatory=$true,Position=1,HelpMessage="Please provide the exact name of the Workplace Analytics MSOL Account SKU license for the applicable tenant.")]
        [ValidateNotNullorEmpty()]
        [string]$LicenseSKU
        )
        #Simple function to connect to Office 365 MSOL PowerShell.
        Function Connect-O365PowerShell {
            try {
                Import-Module MSOnline -ErrorAction Stop
                Write-Output "Successfully imported the Azure Active Directory PowerShell module, proceeding..."
            }
            catch {
                Write-Error -Message "Windows Azure Active Directory PowerShell module could not be found, please install the module and run this script again!"
                break
            }
            if(Get-Module -Name MSOnline) {
                try {
                    Connect-MsolService -ErrorAction Stop
                    Write-Output "Successfully connected to Office 365 MSOL, proceeding..."
                }
                catch {
                    Write-Error "Could not connect to Office 365 MSOL due to the following exception.`r`n$($_.Exception.Message)"
                    break
                }
            }
        }
        #Simple function to get to MSOL SKU information.
        Function Get-WorkplaceAnalyticsSku {
            param ($searchString)
            $O365MsolSKUs = Get-MsolAccountSku
            try {
                $wpaSku = $O365MsolSKUs | Where-Object { $_.AccountSkuId -like $searchString }
                if ($wpaSku) {
                    Write-Host "Office365 tenant possesses the correct WorkplaceAnalytics license, proceeding..."
                    [int]$availableLicenses = $wpaSku.ActiveUnits - $wpaSku.ConsumedUnits
                    Write-Host "Using Sku: $($wpaSku.AccountSkuId), Total Licenses: $($wpaSku.ActiveUnits), Used Licenses: $($wpaSku.ConsumedUnits), Available Licenses: $($availableLicenses)"
                    return $wpaSku
                }
                else {
                    Write-Error "Script could not find matching WorkplaceAnalytics license using $searchString on Office365 tenant. Here are the available SKU's for this tenant:"
                    Write-warning ($O365MsolSKUs | out-string)
                    write-warning "Please Rerun script and specify a SKU above with parameter -LicenseSKU {sku} including the appropriate WORKPLACE_ANALYTICS SKU"  
                    exit 1
                }
            }
            catch {
                 Write-Error "Failed to determine the Office365 tenant licenses, script cannot proceed!`n$_."
                 exit 1
            }
        }
        #Start-Transcript to keep a simple log of all stream output of the successes and failures of the execution and to set StrictMode.
        Start-Transcript
        Set-StrictMode -version 2
        #Simple if block to test the CSV parameter input and confirm the path is valid and contains a file.
        if (!(Test-Path $CSV)) {
          Write-Error "CSV file could not be found, please ensure that the location is correct and you have the proper permissions to read the file then try again.`r`n$($_.Exception.Message)"
        break
        }
        Write-Output "CSV file was found, proceeding..."
        try {
           #If the CSV is valid, this tries to import the contents into a user's CSV array that's used for processing.
           [array]$users = @(Import-Csv $CSV -ErrorAction Stop)
            Write-Output "CSV file was imported to process successfully, proceeding..."
         }
         catch {
            Write-Error "Failed to import CSV for processing due to the following exception.`r`n$($_.Exception.Message)"
            break
         }
        #After CSV formatting is verified, check for Email values in the file.
        if(($users.count) -le 0) {
           Write-Error "The CSV provided did not contain any valid SMTP data. Please check the CSV file and try again."
           break
        }
        Write-Host "Found $($users.count) items in the CSV to process"
        #Check the CSV contains the proper Email header.
        if ($users | Get-Member Email) {
           Write-Host "CSV file is valid, proceeding..."
        }
        else {
           Write-Warning "CSV is missing Email header. Please check the CSV file specified and update the CSV to include the header: Email"
           break
         }
         #Calling Connect-O365PowerShell function to establish connection.
         try {
             Connect-O365PowerShell -ErrorAction Stop
         }
         catch {
            Write-Error "Failed to successfully connect to Azure Active Directory PowerShell due to the following exception.`r`n$($_.Exception.Message)"
            break
         }
         #Try to pull MSOL SKUs.
         if ([string]::isnullorempty($LicenseSku)) {
            $wpaSearch = "*:WORKPLACE_ANALYTICS"
         }
         else {
            $wpaSearch = "*$LicenseSku*"
         }
         $LicenseSku = Get-WorkplaceAnalyticsSku -searchString $wpaSearch
         $NumofSuccessfullyLicensed = 0
         $NumofErrorLicensed = 0
         $NumOfAlreadyLicensed = 0
         $NumOfUsersNotFound = 0
         [System.Collections.ArrayList]$UsersNotFound =@()
         [System.Collections.ArrayList]$UsersFailedtoLicense =@()
         #If the user's array contains the Email member who is created by importing a CSV and the object count of the user's array is greater than zero (0), the processing block is entered and a foreach loop is used to process the array contents.
         Foreach($user in $users) {
            #An attempt is made to find the user through the UserPrincipalName parameter. If an error occurs, the catch block will try to find the user through a ProxyAddresses attribute regex comparison. An absolute match after the colon of the address in the array is required to increase the accuracy of the find.
            $userIndex = $users.Indexof($user)
            Write-Progress -Activity "Assigning Workplace Analytics Licenses, currently on $($userIndex + 1) of $($users.Count) Currently searching for user $($user.Email)" -PercentComplete ($userIndex / $users.Count * 100) -Id 1
            try {
                $msolUser = Get-MsolUser -UserPrincipalName $user.Email -ErrorAction Stop
             }
             catch {
                Write-Warning "Failed to find user $($user.Email) through UPN lookup, attempting ProxyAddress attribute...`n$_"
                $msolUser = Get-MsolUser -All | Where-Object {$_.ProxyAddresses -match "\:$($user.Email)"}
             }
             if($msolUser) {
                 #If the msolUser variable is not null, the following block will be entered where an attempt is made to add the LicenseSKU parameter to the MSOL user.
                 if ($msolUser.Licenses.AccountSkuId -contains $LicenseSKU.AccountSkuId) {
                    Write-Warning "User $($msolUser.UserPrincipalName) was found but is already licensed for WorkplaceAnalytics, skipping licensing."
                    $NumOfAlreadyLicensed++
                 }
                 else {
                    Write-Output "User $($user.Email) found, attempting to license..."
                    try {
                       Set-MsolUserLicense -UserPrincipalName $msolUser.UserPrincipalName -AddLicenses $LicenseSKU.AccountSkuId -ErrorAction Stop | Out-Null
                       Write-Output "Successfully licensed user $($msolUser.UserPrincipalName) with $($LicenseSKU.AccountSkuId) license."
                       $NumofSuccessfullyLicensed++
                     }
                     catch {
                        Write-Error "Failed to license user $($msolUser.UserPrincpalName) due to the following exception.`r`n$($_.Exception.Message)"
                        $NumofErrorLicensed++
                        $UsersFailedtoLicense.Add($user.Email) | Out-Null
                     }
                 }
             }
             else {
                $NumOfUsersNotFound++
                $NumofErrorLicensed++
                $UsersNotFound.Add($user.Email) | Out-Null
                Write-Error "Could not find user $($user.Email), skipping!"
                continue
             }
         }
         if ($UsersFailedtoLicense.count -ne 0) {
             Write-Output "`nThe following $($UsersFailedtoLicense.count) failed to License:`n"
             Write-Output $UsersFailedtoLicense
         }
         if ($UsersNotFound.Count -ne 0) {
             Write-Output "`nThe following $($UsersNotFound.count) users were not found:`n"
             Write-Output $UsersNotFound
         }
         $finaloutput = "`nScript completed, Total number of users licensed:$NumofSuccessfullyLicensed"
         $finaloutput += "`nTotal number of users that were already licensed:$NumOfAlreadyLicensed"
         $finaloutput += "`nErrors encountered:$NumofErrorLicensed"
         $finaloutput += "`nTotal users not found:$NumOfUsersNotFound"
    
         Write-Output $finaloutput
       Stop-Transcript
    

    PowerShell 환경을 준비 하 고 입력 파일을 구성한 후에는 CSV 사용자 파일이 스크립트와 같은 디렉터리에 있는지 확인 한 다음 스크립트를 실행할 수 있습니다.After the PowerShell environment is prepared and the input file constructed, confirm that the CSV user file is in the same directory as the script, and then you can execute the script.

  3. Windows PowerShell을 시작 하 고 다음 명령을 실행 합니다.Start Windows PowerShell and run the following command:

     C:\Scripts\Add-WpALicense.ps1 -CSV <CSVLocation>
    

    Note

    여기에는 <CSVLocation> CSV 입력 파일의 전체 경로 (예: C:\Scripts\InputFile.csv)가 포함 되어야 합니다.That the <CSVLocation> should contain the full path to the CSV input file, such as C:\Scripts\InputFile.csv.

  4. 메시지가 표시 되 면 라이선스를 추가할 테 넌 트에 대 한 Office 365 전역 관리자 자격 증명을 입력 합니다.When prompted, enter the Office 365 global administrator credentials for the tenant where the licenses are to be added.

    필요한 모든 입력이 충족 되 면 이제 CSV 목록에 대해 스크립트가 실행 된 다음 라이선스가 사용자에 게 할당 됩니다.If all the required inputs are satisfied, the script executes now against the CSV list, and then licenses are assigned to users. 스크립트 실행 중에 모든 성공 및 실패가 명령줄에 표시 되 고 녹음 내용이 문서 폴더에 저장 됩니다.During the script execution, all successes and failures are shown on the command line and a transcript is saved in the Documents folder.

FAQFAQ

스크립트를 실행 하는 동안 문제가 발생 했습니다. 스크립트 작업 로그가 있습니까?Something went wrong during the script execution. Is there a log of the script actions?

예, 스크립트를 실행 한 사용자의 문서 폴더에서 각 실행에 대 한 스크립트 성적 증명서를 찾을 수 있습니다.Yes, you can find a script transcript for each execution in the Documents folder for the person who executed the script.

전자 메일 주소 입력이 MSOL id의 UserPrincipalName가 아니면 작동 하나요?Will an email address input work if it is not the UserPrincipalName of any MSOL identity?

스크립트 논리는 먼저 CSV 파일의 전자 메일 주소를 사용 하 여 UserPrincipalName를 통해 MSOL id를 찾으려고 시도 합니다.The script logic first attempts to find the MSOL identity through the UserPrincipalName by using the email address from the CSV file. 이 시도가 실패 하면 스크립트는 ProxyAddresses 속성 내에서 CSV 파일의 전자 메일 주소를 포함 하는 MSOL 개체를 찾으려고 시도 합니다.If this attempt fails, the script tries to find any MSOL object that contains the email address from the CSV file within the ProxyAddresses property. 여전히 사용자를 찾을 수 없는 경우 전자 메일은 존재 하지 않는 것으로 간주 되며 건너뜁니다.If a user still cannot be found, the email is deemed not to exist and is skipped.

MFA (다단계 인증)를 사용 하 여이 작업을 수행 합니까?Does this work with Multi-Factor Authentication (MFA)?

이 스크립트는 Connect-msolservice cmdlet이 Azure의 ADAL (Active Directory 인증 라이브러리)을 지원 하기 때문에 Multi-factor Authentication과 함께 작동 합니다.This script works with Multi-Factor Authentication because the Connect-MsolService cmdlet supports Azure Active Directory Authentication Library (ADAL).

문제 해결Troubleshooting

오류: 제공한 CSV에 유효한 SMTP 데이터가 포함 되어 있지 않습니다. CSV 파일을 확인 하 고 다시 시도 하세요.Error: The CSV provided did not contain any valid SMTP data. Please check the CSV file and try again.

CSV 파일에 적절 한 헤더와 구문 분석할 유효한 전자 메일 주소가 포함 되어 있는지 확인 합니다.Check the CSV file contains the proper header and valid email addresses to parse

오류: 사용자 user1@contoso.com를 찾을 수 없습니다 (건너뜁니다!).Error: Could not find user user1@contoso.com, skipping!

전자 메일이 올바르게 확인 되는지 확인 합니다.Check that the email properly resolves.

오류:이 개체에서 ' AccountSkuId ' 속성을 찾을 수 없습니다. 속성이 있는지 확인 합니다.Error: The property 'AccountSkuId' cannot be found on this object. Verify that the property exists.

사용자에 게 적절 한 EXO 라이선스가 있는지 확인 합니다.Check that the user has the proper EXO license.

오류: CSV 파일을 찾을 수 없음 ...Error: The CSV file could not be found ...

를 정의할 때 올바른 파일을 지정 하 -CSV 고 스크립트를 실행 하는 사용자에 게 파일을 읽을 수 있는 권한이 있는지 확인 합니다.Confirm the correct file is specified when defining the -CSV and that the user running the script has permissions to read the file.

스크립트가 성공 하지만 출력 보고서: 스크립트가 완료 되었지만 사용이 허가 된 총 사용자 수가 영 (0) 인 경우If the script is successful but the output reports: Script completed, but the total number of users licensed is zero (0).

  1. 사용자에 게 라이선스가 아직 사용 되지 않았는지 확인 합니다.Confirm the user is not already licensed.
  2. 사용자가 올바른 Exchange Online 계획을 사용 하 고 있는지 확인 합니다.Confirm the user is using the correct Exchange Online plan.
  3. 사용자 UPN 또는 프록시 전자 메일 주소가 환경에서 확인 되는지 확인 합니다.Confirm the users UPN or proxy email address resolves in the environment.