MicrosoftTeamsのメンバー管理をPowerShellで行う

MicrosoftTeamsにはPowershellの管理Moduleが存在します。これを使ってメンバー管理の自動化をやってみようと思います。

MicrosoftTeamsモジュールのインストール

PowershellでInstall-Module MicrosoftTeamsを実行してやるとインストールできます。

管理者権限がないとかProxyの中にいるとかうまくインストールできない場合は下記をみてください。

認証プロキシ・管理者権限無しでPowershellモジュールをインストールする

MicrosoftTeamsモジュールのインポート

Installが終わったらImport-Module MicrosoftTeamsでImportします。この時に-Vervorseオプションを付けるとImportしたコマンド一覧が表示されます。

PS C:\> Import-Module MicrosoftTeams -Verbose
詳細: パス 'C:\Program Files\WindowsPowerShell\Modules\MicrosoftTeams\MicrosoftTeams.psd1' からモジュールを読み込んでいます。
詳細: コマンドレット 'Add-TeamUser' をインポートしています。
詳細: コマンドレット 'Get-CsPolicyPackage' をインポートしています。
詳細: コマンドレット 'Get-CsUserPolicyPackage' をインポートしています。
詳細: コマンドレット 'Get-CsUserPolicyPackageRecommendation' をインポートしています。
詳細: コマンドレット 'Get-Team' をインポートしています。
詳細: コマンドレット 'Get-TeamChannel' をインポートしています。
詳細: コマンドレット 'Get-TeamsApp' をインポートしています。
詳細: コマンドレット 'Get-TeamUser' をインポートしています。
詳細: コマンドレット 'Grant-CsUserPolicyPackage' をインポートしています。
詳細: コマンドレット 'New-CsBatchPolicyPackageAssignmentOperation' をインポートしています。
詳細: コマンドレット 'New-Team' をインポートしています。
詳細: コマンドレット 'New-TeamChannel' をインポートしています。
詳細: コマンドレット 'New-TeamsApp' をインポートしています。
詳細: コマンドレット 'Remove-Team' をインポートしています。
詳細: コマンドレット 'Remove-TeamChannel' をインポートしています。
詳細: コマンドレット 'Remove-TeamsApp' をインポートしています。
詳細: コマンドレット 'Remove-TeamUser' をインポートしています。
詳細: コマンドレット 'Set-Team' をインポートしています。
詳細: コマンドレット 'Set-TeamArchivedState' をインポートしています。
詳細: コマンドレット 'Set-TeamChannel' をインポートしています。
詳細: コマンドレット 'Set-TeamPicture' をインポートしています。
詳細: コマンドレット 'Set-TeamsApp' をインポートしています。

この中で普通の管理者向けに有用なのはTeamUser系だと思います。ActiveDirectoryと連動はするんですがグループで登録すると個々のIDに分解されて登録されるのでActiveDirectory側のグループメンテナンスに追随しないんですよ。なので運用開始したらメンバーのメンテナンスをしないといけません。なのでメンバー一覧を取得（Get-TeamUser）して手元の一覧と突合して削除（Remove-TeamUser）したり登録したり（Add-TeamUser)したりすればメンテナンスしてやれそうです。

MicrosoftTeamsへのConnect

最初にPowershellをTeams自体にConnectしないといけません。まずConnect-MicrosoftTeamsコマンドレットを使います。自分はMFA認証有効な環境なのでUserIDを入力する画面から上がってきてすぐ解決するんですが、そうでない方は下記ヘルプを参照ください。

PS C:\Windows\system32> get-help Connect-MicrosoftTeams -Full

名前
    Connect-MicrosoftTeams
    

概要
    The Connect-MicrosoftTeams cmdlet connects an authenticated account to use for Microsoft Teams cmdlet requests. 
    You can use this authenticated account only with Microsoft Teams cmdlets.
    
    
構文
    Connect-MicrosoftTeams -AadAccessToken <String> -AccountId <String> [-Confirm] [-LogFilePath <String>] [-LogLeve
    l <LogLevel>] [-MsAccessToken <String>] [-TenantId <String>] [-WhatIf] [<CommonParameters>]
Connect-MicrosoftTeams [-AccountId <String>] [-Confirm] [-Credential <PSCredential>] [-LogFilePath <String>] [-L
    ogLevel <LogLevel>] [-TenantId <String>] [-WhatIf] [-TeamsEnvironmentName <String>] [<CommonParameters>]
Connect-MicrosoftTeams -ApplicationId <String> -CertificateThumbprint <String> [-Confirm] [-LogFilePath <String>
    ] [-LogLevel <LogLevel>] -TenantId <String> [-WhatIf] [<CommonParameters>]
説明
    
    

パラメーター

    -AadAccessToken <String>

        Specifies a Azure Active Directory Graph access token.
        必須                         true
 
        位置                         named

        既定値                       None

        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false
 
    -AccountId <String>

        Specifies the ID of an account. You must specify the UPN of the user when authenticating with a user access 
token.

        必須                         false
        位置                         named

        既定値                       None

        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false

      -ApplicationId <String>

        Specifies the application ID of the service principal.
       

        必須                         true

        位置                         named

        既定値                       None

        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false
     
  
    -CertificateThumbprint <String>
        Specifies the certificate thumbprint of a digital public key X.509 certificate of a user account that has pe
rmission to perform this action.
        
  
        必須                         true
        位置                         named
        既定値                       None

        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false
       
 
    -Confirm [<SwitchParameter>]

        Prompts you for confirmation before running the cmdlet.
       
 
       必須                         false

        位置                         named

        既定値                       False
        パイプライン入力を許可する   False

        ワイルドカード文字を許可する false
     
  
    -Credential <PSCredential>
        Specifies a PSCredential object. For more information about the PSCredential object, type Get-Help Get-Credential.
The PSCredential object provides the user ID and password for organizational ID credentials.
        

        必須                         false

        位置                         named
        既定値                       None

        パイプライン入力を許可する   False

        ワイルドカード文字を許可する false
     
  
    -LogFilePath <String>
        The path where the log file for this PowerShell session is written to. Provide a value here if you need to d
eviate from the default PowerShell log file location.
        
        必須                         false
        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false
      
  
    -LogLevel <LogLevel>
        Specifies the log level.  The acceptable values for this parameter are:

        - Info
        

        - Error
       
 
       - Warning
        

        - None
        
     
   
     The default value is Info.
        
        
必須                         false
        位置                         named

        既定値                       None
        パイプライン入力を許可する   False

        ワイルドカード文字を許可する false
       
 
    -MsAccessToken <String>

        Specifies a Microsoft Graph access token.
       
 
       必須                         false

        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false
     
  
    -TenantId <String>
        Specifies the ID of a tenant.
If you do not specify this parameter, the account is authenticated with the home tenant.You must specify the TenantId parameter to authenticate as a service principal or when using Microsoft accou
nt.

        必須                         false

        位置                         named
        既定値                       None

        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false
   
  
    -WhatIf [<SwitchParameter>]

        Shows what would happen if the cmdlet runs. The cmdlet is not run.
     
   
     必須                         false
        位置                         named
        既定値                       False
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false
     
  
    -TeamsEnvironmentName <String>
        Use this setting if your organization is in one of the Teams Government Cloud environments.
Specify "TeamsGCCH" if your organization is in the GCC High Environment.  Specify "TeamsDOD" if your organization is in the DoD Environment.
       
 
       必須                         false
        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false
      
 
    <CommonParameters>

        このコマンドレットは、次の共通パラメーターをサポートします: Verbose、Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
OutBuffer, PipelineVariable、および OutVariable。詳細については、
about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216) 
を参照してください。
        Tips for troubleshooting: 1. Confirm SAML 2.0 is being used.  IDP is outputting invalid SAML information. Needs to have SAML 2.0 vs. SAML 1.0 for the module to connect. You might experience an error if the Identity P
rovider (IDP) only allows the use of SAML1.0 when trying to auth via basic authentication.  Which in turn, isn't expected to work because the cmdlet expects either OAUTH2 (which is used when doing just connect-micros
ofteams), or SAML2.0. 2. Confirm you have the latest version of the cmdlet. You can find the version by runn
ing: `get-module -listavailable` and then looking for the MicrosoftTeams name and the version to the left of it.

    
    -------------------------- Example 1 --------------------------

    
    PS C:\> Connect-MicrosoftTeams -TeamsEnvironmentName TeamsGCCH

    
    Specifies that the organization being managed is in the Teams GCC High environment, so connect to that environme
nt.

自分の場合はオプションなしで実行すると、MFA認証画面が上がってきて終了します。

PS C:\log> Connect-MicrosoftTeams


Account      : user01@ TenantNeme.onmicrosoft.com 
Environment  : AzureCloud
Tenant       : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
TenantId     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
TenantDomain : TenantNeme.onmicrosoft.com

TeamのGroupIdを調べる

次に操作したいTeamのGroupIdを調べます。下記を実行すれば自分が所属しているTeamのGroupIdが返ってくるはずです。

PS C:\> Get-Team -User user01@ TenantNeme.onmicrosoft.com

GroupId                              DisplayName        Visibility  Archived  MailNickName       Description       
-------                              -----------        ----------  --------  ------------       -----------       
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx team01    Private     False     msteams_xxxxxx     〇〇関係のチーム

ここで調べられたIdでグループを操作できます。詳しくはGet-Teamのヘルプを御覧ください。

PS C:\> Get-Help Get-Team -Full

名前
    Get-Team

概要
    This cmdlet supports retrieving teams with particular properties/information, including all teams that a specific user belongs to, all teams that have been archived, all teams with a specific display name, or all teams in the organization.


構文
    Get-Team [-User <String>] [-Archived <Boolean>] [-DisplayName <String>] -GroupId <String> [-MailNickName <String>] [-Visibility <String>] [<CommonParameters>]

    Get-Team [-User <String>] [-Archived <Boolean>] [-DisplayName <String>] [-MailNickName <String>] [-Visibility <String>] [<CommonParameters>]


説明
    This cmdlet supports retrieving teams with particular properties/information, including all teams that a specific user belongs to, all teams that have been archived, all teams with a specific display name, or all teams in the organization.

    Note: depending on the number of teams and O365 Groups in your organization and which filters you are using, this cmdlet can take upwards of ten minutes to run.  Some of the input parameters are guaranteed unique (e.g. GroupId), and others serve as filters (e.g. -Archived).


パラメーター
    -User <String>
        User's UPN (user principal name - e.g. johndoe@example.com)

        必須                         false
        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false

    -Archived <Boolean>
        If $true, filters to return teams that have been archived.  If $false, filters to return teams that have not been archived.  Do not specify any value to return teams that match filter regardless of archived state.  This is a filter rather than an exact match.

        必須                         false
        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false

    -DisplayName <String>
        Filters to return teams with a full match to the provided displayname.  As displayname is not unique, this acts as a filter rather than an exact match.

        必須                         false
        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false

    -GroupId <String>
        Specify the specific GroupId (as a string) of the team to be returned.  This is a unique identifier and returns exact match.

        必須                         true
        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false

    -MailNickName <String>
        Specify the mailnickname of the team that is being returned.  This is a unique identifier and returns exact match.

        必須                         false
        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false

    -Visibility <String>
        Filters to return teams with a set "visibility" value.  Accepted values are "Public" or "Private".  Do not specify any value to return teams that match filter regardless of visibility.  This is a filter rather than an exact match.

        必須                         false
        位置                         named
        既定値                       None
        パイプライン入力を許可する   False
        ワイルドカード文字を許可する false

    <CommonParameters>
        このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
        Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
        OutBuffer, PipelineVariable、および OutVariable。詳細については、
        about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216) 
        を参照してください。 

入力
    UPN, UserID



出力
    Team



メモ




    -------------------------- Example 1 --------------------------

    PS> Get-Team -User dmx1@example.com

    Returns all teams that a user (dmx1@example.com) belongs to
    -------------------------- Example 2 --------------------------

    PS> Get-Team -Archived $true -Visibility Private

    Returns all teams that are private and have been archived.
    -------------------------- Example 3 --------------------------

    PS> Get-Team -MailNickName "BusinessDevelopment"

    Returns the team that matches the specified MailNickName

関連するリンク
    New-Team 
    Set-Team

Groupのメンバーを取得する

GroupIdがわかると、メンバー一覧が取得できます。

PS C:\> Get-TeamUser -GroupId xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

この結果を配列にいれるなりして、手元のCSVと比較したりActiveDirectoryに問い合わせるなりして管理ができます。PowerShellからActiveDirectoryに問い合わせる手段は下記を参照ください。

ドメインコントローラーサーバー以外からActiveDirectoryに問い合わせをする

メンバーを削除する

既存のメンバーを削除するにはRemove-TeamUserで出来ます。詳しくは下記のヘルプをご覧ください。

PS C:\> Get-Help Remove-TeamUser -Full

名前
    Remove-TeamUser

概要
    Remove an owner or member from a team, and from the unified group which backs the team.

    Note: the command will return immediately, but the Teams application will not reflect the update immediately. The Teams application may need to be open for up to an hour before changes are reflected.

    Note: last owner cannot be removed from the team.


構文
    Remove-TeamUser -GroupId <String> -User <String> -Role <String> [<CommonParameters>]


説明



パラメーター
    -GroupId <String>
        GroupId of the team

        必須                         true
        位置                         named
        既定値                       None
        パイプライン入力を許可する   True (ByPropertyName)
        ワイルドカード文字を許可する false

    -User <String>
        User's UPN (user principal name - e.g. johndoe@example.com)

        必須                         true
        位置                         named
        既定値                       None
        パイプライン入力を許可する   True (ByPropertyName)
        ワイルドカード文字を許可する false

    -Role <String>
        Specify the role of the user you are removing from the team. Accepts "Owner" and "Member" as possible values. If cmdlet is called with -Role parameter as "Member" then the specified user is removed from the Team completely even if they were the owner of the Team. If "Owner" is specified in the -Role parameter then the specified user is removed as an owner of the team but stays as a team member. Note: The last owner cannot be removed from the team.

        必須                         true
        位置                         named
        既定値                       None
        パイプライン入力を許可する   True (ByPropertyName)
        ワイルドカード文字を許可する false

    <CommonParameters>
        このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
        Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
        OutBuffer, PipelineVariable、および OutVariable。詳細については、
        about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216) 
        を参照してください。 

    -------------------------- Example 1 --------------------------

    Remove-TeamUser -GroupId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df -User dmx@example.com -Role Owner

メンバーを追加する

同じようにAdd-TeamUserで出来ます。ヘルプを掲示しますのでご覧ください。

PS C:\> Get-Help Add-TeamUser -Full

名前
    Add-TeamUser

概要
    The `Add-TeamUser` adds an owner or member to the team, and to the unified group which backs the team.


構文
    Add-TeamUser -GroupId <String> -User <String> [-Role <String>] [<CommonParameters>]


説明
    This cmdlet adds an owner or member to the team, and to the unified group which backs the team.

    > [!Note] > The command will return immediately, but the Teams application will not reflect the update immediately. The Teams application may need to be open for up to an hour before changes are reflected.

    It doesn't work in the same way that the Teams application. If you add an owner in the application the user is also added as member to the unified group. Using this cmdlet, it will add the user only as an owner to the unified group, not as a member. Then you can run the cmdlet again to add the user as memb
    er.


パラメーター
    -GroupId <String>
        GroupId of the team.

        必須                         true
        位置                         named
        既定値                       None
        パイプライン入力を許可する   True (ByPropertyName)
        ワイルドカード文字を許可する false

    -User <String>
        User's UPN (user principal name - e.g. johndoe@example.com).

        必須                         true
        位置                         named
        既定値                       None
        パイプライン入力を許可する   True (ByPropertyName)
        ワイルドカード文字を許可する false

    -Role <String>
        Member or Owner. If Owner is specified then the user is also added as a member to the Team backed by unified group.

        必須                         false
        位置                         named
        既定値                       Member
        パイプライン入力を許可する   True (ByPropertyName)
        ワイルドカード文字を許可する false

    <CommonParameters>
        このコマンドレットは、次の共通パラメーターをサポートします: Verbose、
        Debug、ErrorAction、ErrorVariable、WarningAction、WarningVariable、
        OutBuffer, PipelineVariable、および OutVariable。詳細については、
        about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216) 
        を参照してください。 

入力
    GroupId, User, Role



出力

メモ




    -------------------------- Example 1 --------------------------

    Add-TeamUser -GroupId 31f1ff6c-d48c-4f8a-b2e1-abca7fd399df -User dmx@example.com

    This example adds the user "dmx@example.com" to a group with the id "31f1ff6c-d48c-4f8a-b2e1-abca7fd399df".

まとめ

Connect-MicrosoftTeamsさえ突破できれば、*-TeamUserコマンドレットでチームメンバーは管理できます。チームを大量に作ったり消したりよりはチームメンバー管理のほうがよくあることだと思うので参考にしてください。