Teams Phone Agentのスパム検出テンプレートは、Frontier Public Preview環境であれば、Teams PowerShellのGet-CsMainlineAttendantSpamDetectionTemplate、Set-CsMainlineAttendantSpamDetectionTemplate、Remove-CsMainlineAttendantSpamDetectionTemplateを使って取得・変更・削除できます。
安全な管理手順は、現行設定の取得、バックアップ、割り当て先の確認、変更または割り当て解除、再取得による検証の順です。特に削除時は、対象テンプレートをTeams Phone Agentへ割り当てたままRemoveを実行してはいけません。先にすべての割り当てを解除し、参照がゼロになったことを確認してから削除します。2026年7月時点で、Teams Phone Agentは旧称Mainline Attendantであり、Frontier Public Previewの対象機能です。(Microsoft Learn)
Teams Phone Agentのスパム検出テンプレート管理で押さえるべき基本
スパム検出テンプレートの管理に使用する主なコマンドは次の3つです。
| コマンド | 用途 | 主な指定方法 | 実務上の注意 |
|---|---|---|---|
Get-CsMainlineAttendantSpamDetectionTemplate | テンプレートの取得 | 全件取得、または-Idで1件取得 | 変更・削除前の確認に必ず使用する |
Set-CsMainlineAttendantSpamDetectionTemplate | 既存テンプレートの変更 | -Instanceに取得済みオブジェクトを渡す | プロパティを直接パラメーター指定する方式ではない |
Remove-CsMainlineAttendantSpamDetectionTemplate | テンプレートの削除 | -IdにGUIDを指定 | Teams Phone Agentから割り当てを外してから実行する |
Getで-Idを省略すると、テナント内に設定されているスパム検出テンプレートの一覧を取得できます。Setは、Getで取得したオブジェクトのプロパティを変更し、そのオブジェクトを-Instanceへ渡す方式です。RemoveではテンプレートのGUIDを-Idへ指定します。(Microsoft Learn)
製品名はTeams Phone Agentへ変更されていますが、PowerShellコマンド名には旧称のMainlineAttendantが残っています。コマンドを検索するときは、TeamsPhoneAgentではなくCsMainlineAttendantを含む名前を使用してください。
実行前にコマンドとモジュールの状態を確認する
Teams Phone AgentはPublic Preview機能です。そのため、Frontier Public Previewへ参加していないテナントや、対象コマンドが含まれないMicrosoftTeamsモジュールでは、コマンドが見つからないことがあります。(Microsoft Learn)
最初にTeamsへ接続し、必要なコマンドが現在のセッションで認識されているか確認します。
Import-Module MicrosoftTeams
Connect-MicrosoftTeams
$requiredCommands = @(
"Get-CsMainlineAttendantSpamDetectionTemplate",
"Set-CsMainlineAttendantSpamDetectionTemplate",
"Remove-CsMainlineAttendantSpamDetectionTemplate"
)
$requiredCommands | ForEach-Object {
$command = Get-Command $_ -ErrorAction Stop
[pscustomobject]@{
Name = $command.Name
Module = $command.Source
Version = $command.Version
}
}インストールされているMicrosoftTeamsモジュールも確認しておきます。
Get-Module MicrosoftTeams -ListAvailable |
Sort-Object Version -Descending |
Select-Object Name, Version, Pathコマンドの構文は、Web上の説明だけでなく、実際の管理端末で確認してください。
Get-Command Get-CsMainlineAttendantSpamDetectionTemplate -Syntax
Get-Command Set-CsMainlineAttendantSpamDetectionTemplate -Syntax
Get-Command Remove-CsMainlineAttendantSpamDetectionTemplate -Syntax
Get-Help Set-CsMainlineAttendantSpamDetectionTemplate -FullPublic Previewのドキュメントには、記述の揺れが残る場合があります。たとえば、Set-CsMainlineAttendantSpamDetectionTemplateの公式例では取得したテンプレートオブジェクトを-Instanceへ渡していますが、パラメーター説明には別種類のテンプレート名が残っています。また、作成コマンドの構文とパラメーター説明でリスト名の表記が一致しない箇所もあります。実際の運用では、現在のモジュールが返すGet-Command -Syntax、Get-Help、Get-Memberを優先して判断するのが安全です。(Microsoft Learn)
スパム検出テンプレートの一覧と詳細を取得する
テナント内の全テンプレートを取得する
$templates = @(
Get-CsMainlineAttendantSpamDetectionTemplate -ErrorAction Stop
)
$templates |
Select-Object Id, Name, Description, EnableSpamDetection, Action |
Format-Table -AutoSize表示されるプロパティが想定と異なる場合は、整形せずにすべて確認します。
$templates | Format-List *または、オブジェクトの型とプロパティ構成を確認します。
$templates | Get-MemberIDを指定して1件だけ取得する
テンプレートの一意な識別子はGUIDです。Getでは-Identityではなく-Idを使います。
$templateId = [Guid]"3a4b3d9b-91d8-4fbf-bcff-6907f325842d"
$template = Get-CsMainlineAttendantSpamDetectionTemplate `
-Id $templateId `
-ErrorAction Stop
$template | Format-List *-Idは省略可能ですが、ワイルドカードやパイプライン入力には対応していません。変更対象を確実に特定するには、一覧から名前だけで選ばず、GUIDを記録して操作してください。(Microsoft Learn)
変更前に設定をバックアップする
スパム検出テンプレートの変更コマンドには、公開されている構文上、-WhatIfや-Confirmが示されていません。そのため、変更前のオブジェクトを保存し、変更後に差分を確認する運用が重要です。(Microsoft Learn)
$backupDirectory = Join-Path $PWD "teams-phone-agent-spam-backup"
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
New-Item -ItemType Directory `
-Path $backupDirectory `
-Force | Out-Null
$template | Export-Clixml `
-Path (Join-Path $backupDirectory "$timestamp-$($template.Id).clixml")
$template |
ConvertTo-Json -Depth 20 |
Set-Content `
-Path (Join-Path $backupDirectory "$timestamp-$($template.Id).json") `
-Encoding utf8CLIXMLはPowerShellオブジェクトの構造確認に、JSONは人が変更前後を比較する用途に向いています。
ただし、保存したCLIXMLをそのままSetへ渡せば必ず復元できるとは限りません。サービス側のオブジェクト型やPublic Preview中の仕様が変わる可能性があるため、バックアップは主に設定値の記録と手動復旧の根拠として扱います。
テンプレートが割り当てられているTeams Phone Agentを調べる
削除前だけでなく、動作を大きく変更する前にも、対象テンプレートを使用しているTeams Phone Agentを洗い出します。
Teams Phone Agentへのテンプレート割り当てには、Auto AttendantオブジェクトのSpamDetectionTemplateIdが使用されます。新しいAuto Attendantを作成するコマンドでも、Teams Phone AgentへテンプレートIDを割り当てるパラメーターとして定義されています。(GitHub)
Auto Attendantを100件ずつ取得する
Get-CsAutoAttendantは、既定では最初の100件を取得し、1回の取得上限も100件です。100件を超えるテナントで単純にGet-CsAutoAttendantだけを実行すると、101件目以降の割り当てを見落とす可能性があります。-Firstと-Skipを使ってページングしてください。(Microsoft Learn)
function Get-AllCsAutoAttendant {
[CmdletBinding()]
param()
$allAutoAttendants = @()
$skip = 0
do {
$page = @(
Get-CsAutoAttendant `
-First 100 `
-Skip $skip `
-ErrorAction Stop
)
$allAutoAttendants += $page
$skip += $page.Count
}
while ($page.Count -eq 100)
return $allAutoAttendants
}対象テンプレートの割り当て先を抽出する
$templateId = [Guid]"3a4b3d9b-91d8-4fbf-bcff-6907f325842d"
$templateIdText = $templateId.ToString()
$allAutoAttendants = @(Get-AllCsAutoAttendant)
$objectsWithSpamProperty = @(
$allAutoAttendants | Where-Object {
$null -ne $_.PSObject.Properties["SpamDetectionTemplateId"]
}
)
if (
$allAutoAttendants.Count -gt 0 -and
$objectsWithSpamProperty.Count -eq 0
) {
throw @"
取得したAuto AttendantにSpamDetectionTemplateIdプロパティがありません。
モジュール、Public Previewの展開状況、オブジェクト構造を確認してください。
割り当てを確認できない状態では削除しないでください。
"@
}
$assignedAgents = @(
$objectsWithSpamProperty | Where-Object {
[string]::Equals(
[string]$_.SpamDetectionTemplateId,
$templateIdText,
[System.StringComparison]::OrdinalIgnoreCase
)
}
)
$assignedAgents |
Select-Object Id, Name, SpamDetectionTemplateId, Operator |
Format-Table -AutoSize結果が0件でも、すぐ削除してはいけません。次の点を確認します。
- Auto Attendantを100件単位で最後まで取得できているか
- 正しいテナントへ接続しているか
- 対象テンプレートのGUIDを誤っていないか
SpamDetectionTemplateIdが現在のオブジェクトに公開されているか- 変更直後で反映に時間がかかっていないか
スパム検出時の処理を理解してから変更する
公開されているテンプレート作成コマンドの資料では、スパム検出時のActionとして次の値が定義されています。
| Action | 検出後の処理 | 変更前に確認すること |
|---|---|---|
DisconnectCall | 通話を切断する | 誤検知時に正規の着信も切断される |
TransferCallToOperator | 設定済みオペレーターへ転送する | オペレーター未設定の場合は切断される |
TransferCallToTarget | CallTargetで指定した宛先へ転送する | 転送先の有効性とルーティングループを確認する |
TransferCallToOperatorを選択しても、Teams Phone Agent側にオペレーターが設定されていなければ、スパムと判定された通話は切断されます。TransferCallToTargetでは、CallTargetの指定が必要です。(GitHub)
テンプレートには、スパム検出の有効・無効、強制的にスパムとして扱う番号のリスト、スパムとして扱わない番号のリストなども定義されています。番号リストはE.164形式で管理します。日本の番号であれば、国内先頭の0を外して国番号+81を付ける形式が基本です。
たとえば03-1234-5678は、次のように表します。
+81312345678スパム検出テンプレートを安全に変更する
公式例では、Getでテンプレートを取得し、取得オブジェクトのActionプロパティを変更してから、Setの-Instanceへ渡しています。(Microsoft Learn)
Actionをオペレーター転送へ変更する例
$templateId = [Guid]"66f0dc32-d344-4bb1-b524-027d4635515d"
$desiredAction = "TransferCallToOperator"
$template = Get-CsMainlineAttendantSpamDetectionTemplate `
-Id $templateId `
-ErrorAction Stop
if ($null -eq $template) {
throw "指定したテンプレートを取得できませんでした。"
}
if ($null -eq $template.PSObject.Properties["Action"]) {
throw "取得オブジェクトにActionプロパティがありません。"
}
$backupDirectory = Join-Path $PWD "teams-phone-agent-spam-backup"
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
New-Item -ItemType Directory `
-Path $backupDirectory `
-Force | Out-Null
$template | Export-Clixml `
-Path (Join-Path $backupDirectory "$timestamp-$templateId-before.clixml")
$oldAction = [string]$template.Action
$template.Action = $desiredAction
Set-CsMainlineAttendantSpamDetectionTemplate `
-Instance $template `
-ErrorAction Stop
$verifiedTemplate = Get-CsMainlineAttendantSpamDetectionTemplate `
-Id $templateId `
-ErrorAction Stop
if ([string]$verifiedTemplate.Action -ne $desiredAction) {
throw @"
変更後のActionが想定値と一致しません。
変更前: $oldAction
想定値: $desiredAction
実際値: $($verifiedTemplate.Action)
"@
}
$verifiedTemplate |
Select-Object Id, Name, EnableSpamDetection, Action |
Format-ListSet-CsMainlineAttendantSpamDetectionTemplateの-Instanceは、公式資料上パイプライン入力を受け付けません。次のような書き方は避け、いったん変数へ格納してください。(Microsoft Learn)
# 推奨しない
Get-CsMainlineAttendantSpamDetectionTemplate -Id $templateId |
Set-CsMainlineAttendantSpamDetectionTemplate次のように、取得、編集、反映を分けます。
$template = Get-CsMainlineAttendantSpamDetectionTemplate -Id $templateId
$template.Action = "TransferCallToOperator"
Set-CsMainlineAttendantSpamDetectionTemplate -Instance $template変更後は実通話で確認する
PowerShell上の値が変わっただけでは、運用確認は完了していません。少なくとも次の通話パターンをテストします。
- 通常の外部番号からの着信
- スパムとして扱うテスト番号からの着信
- 除外リストへ登録した番号からの着信
- オペレーター転送
- 指定ターゲットへの転送
- オペレーター不在時や転送失敗時の動作
DisconnectCallへの変更は影響が大きいため、最初から全着信を対象にせず、検証用のTeams Phone Agentや限定した番号で動作確認してから本番へ展開するのが安全です。
削除前にTeams Phone Agentから割り当てを解除する
スパム検出テンプレートは、Teams Phone Agentへ割り当てられていない状態にしてから削除します。Microsoftのドキュメント更新履歴でも、削除対象のテンプレートはTeams Phone Agentへ割り当てられていてはいけないことが明記されています。(GitHub)
割り当て解除には、主に次の2つの方法があります。
別のテンプレートへ置き換える
スパム検出を継続したまま古いテンプレートを廃止する場合は、代替テンプレートへ置き換える方法が安全です。
$agentId = "fa9081d6-b4f3-5c96-baec-0b00077709e5"
$oldTemplateId = [Guid]"66f0dc32-d344-4bb1-b524-027d4635515d"
$replacementTemplateId = [Guid]"3a4b3d9b-91d8-4fbf-bcff-6907f325842d"
# 代替テンプレートが存在することを確認
$replacementTemplate = Get-CsMainlineAttendantSpamDetectionTemplate `
-Id $replacementTemplateId `
-ErrorAction Stop
$agent = Get-CsAutoAttendant `
-Identity $agentId `
-ErrorAction Stop
if ($null -eq $agent.PSObject.Properties["SpamDetectionTemplateId"]) {
throw "SpamDetectionTemplateIdプロパティを確認できません。"
}
if (
-not [string]::Equals(
[string]$agent.SpamDetectionTemplateId,
$oldTemplateId.ToString(),
[System.StringComparison]::OrdinalIgnoreCase
)
) {
throw "このTeams Phone Agentには対象テンプレートが割り当てられていません。"
}
$agent.SpamDetectionTemplateId = $replacementTemplateId
Set-CsAutoAttendant `
-Instance $agent `
-ErrorAction Stop
$verifiedAgent = Get-CsAutoAttendant `
-Identity $agentId `
-ErrorAction Stop
$verifiedAgent |
Select-Object Id, Name, SpamDetectionTemplateId |
Format-List既存Auto Attendantの変更は、Get-CsAutoAttendantで取得したオブジェクトのプロパティを編集し、Set-CsAutoAttendant -Instanceで戻す方式です。SpamDetectionTemplateIdはTeams Phone Agentへテンプレートを割り当てるプロパティとして公開されています。(Microsoft Learn)
テンプレートを未設定にする
スパム検出テンプレートを使わない状態にする場合は、現在のPreview環境で未設定化が許可されていることを確認したうえで、SpamDetectionTemplateIdを$nullにします。
$agentId = "fa9081d6-b4f3-5c96-baec-0b00077709e5"
$agent = Get-CsAutoAttendant `
-Identity $agentId `
-ErrorAction Stop
if ($null -eq $agent.PSObject.Properties["SpamDetectionTemplateId"]) {
throw "SpamDetectionTemplateIdプロパティを確認できません。"
}
$agent.SpamDetectionTemplateId = $null
Set-CsAutoAttendant `
-Instance $agent `
-ErrorAction Stop
$verifiedAgent = Get-CsAutoAttendant `
-Identity $agentId `
-ErrorAction Stop
$verifiedAgent |
Select-Object Id, Name, SpamDetectionTemplateId |
Format-List公開資料には、既存Teams Phone Agentからスパム検出テンプレートだけを解除する専用コマンド例が示されていません。$nullによる未設定化は、Auto Attendantオブジェクトを更新する一般的なパターンとして、まず検証用エージェントで確認してください。
現在のPreview実装で未設定化が受け付けられない場合は、代替テンプレートへ置き換えます。古いテンプレートへの参照が残っている状態で、無理に削除へ進んではいけません。
スパム検出テンプレートを安全に削除する
次のスクリプトは、対象テンプレートの存在確認、全Auto Attendantの取得、割り当て確認、設定バックアップ、IDの再入力、削除後の確認を順番に実行します。
前述のGet-AllCsAutoAttendant関数を定義したセッションで実行してください。
$templateId = [Guid]"5e3a575e-1faa-49ff-83c2-5cf1c36c0e02"
$templateIdText = $templateId.ToString()
# 対象テンプレートの存在確認
$template = Get-CsMainlineAttendantSpamDetectionTemplate `
-Id $templateId `
-ErrorAction Stop
# 全Auto Attendantを取得
$allAutoAttendants = @(Get-AllCsAutoAttendant)
$objectsWithSpamProperty = @(
$allAutoAttendants | Where-Object {
$null -ne $_.PSObject.Properties["SpamDetectionTemplateId"]
}
)
if (
$allAutoAttendants.Count -gt 0 -and
$objectsWithSpamProperty.Count -eq 0
) {
throw @"
SpamDetectionTemplateIdプロパティを確認できません。
割り当て状態を判定できないため、削除を中止します。
"@
}
# 対象テンプレートの割り当て先を検索
$assignedAgents = @(
$objectsWithSpamProperty | Where-Object {
[string]::Equals(
[string]$_.SpamDetectionTemplateId,
$templateIdText,
[System.StringComparison]::OrdinalIgnoreCase
)
}
)
if ($assignedAgents.Count -gt 0) {
$assignedAgents |
Select-Object Id, Name, SpamDetectionTemplateId |
Format-Table -AutoSize
throw @"
対象テンプレートは $($assignedAgents.Count) 件のTeams Phone Agentに割り当てられています。
割り当てを解除または代替テンプレートへ変更してから再実行してください。
"@
}
# 削除前バックアップ
$backupDirectory = Join-Path $PWD "teams-phone-agent-spam-backup"
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
New-Item -ItemType Directory `
-Path $backupDirectory `
-Force | Out-Null
$template | Export-Clixml `
-Path (Join-Path $backupDirectory "$timestamp-$templateId-before-remove.clixml")
$template |
ConvertTo-Json -Depth 20 |
Set-Content `
-Path (Join-Path $backupDirectory "$timestamp-$templateId-before-remove.json") `
-Encoding utf8
# 誤削除防止の手入力確認
$confirmation = Read-Host "削除するテンプレートIDを再入力してください"
if ($confirmation -ne $templateIdText) {
throw "入力されたIDが一致しないため、削除を中止しました。"
}
# 削除
Remove-CsMainlineAttendantSpamDetectionTemplate `
-Id $templateId `
-ErrorAction Stop
# 削除後の存在確認
$remainingTemplates = @(
Get-CsMainlineAttendantSpamDetectionTemplate -ErrorAction Stop
)
$stillExists = @(
$remainingTemplates | Where-Object {
$null -ne $_.PSObject.Properties["Id"] -and
[string]::Equals(
[string]$_.Id,
$templateIdText,
[System.StringComparison]::OrdinalIgnoreCase
)
}
)
if ($stillExists.Count -gt 0) {
throw "削除コマンド実行後も対象テンプレートが存在します。"
}
Write-Host "スパム検出テンプレートを削除し、存在しないことを確認しました。"Remove-CsMainlineAttendantSpamDetectionTemplateは、存在しないIDを指定するとエラーになります。名前から推測したGUIDを使用せず、直前にGetで取得したIDを使ってください。(Microsoft Learn)
複数のTeams Phone Agentから一括で割り当てを外す際の注意点
古いテンプレートが多数のTeams Phone Agentで使われている場合でも、検出したすべてのエージェントから自動的に割り当てを解除し、そのまま削除するスクリプトは推奨できません。
一括変更では、次の問題が起きやすいためです。
- エージェントごとに必要な代替設定が異なる
- オペレーターや転送先の有無が異なる
- 一部のエージェントだけ変更に失敗する
- 変更直後に削除すると、参照状態の反映を確認できない
- 誤ったテンプレートIDで複数の本番エージェントを変更する危険がある
実務では、まず割り当て先をCSVへ出力します。
$assignedAgents |
Select-Object Id, Name, SpamDetectionTemplateId, Operator |
Export-Csv `
-Path ".\assigned-teams-phone-agents.csv" `
-NoTypeInformation `
-Encoding utf8その後、エージェントごとに次の列を追加して変更計画を作ります。
| 管理項目 | 記録内容 |
|---|---|
| Agent ID | Auto AttendantのGUID |
| Agent名 | 管理画面で識別できる名称 |
| 現在のテンプレートID | 削除予定テンプレート |
| 変更方法 | 未設定化、または代替テンプレートへ変更 |
| 代替テンプレートID | 置き換える場合のGUID |
| オペレーター | 設定済みか |
| テスト結果 | 通常着信、スパム判定、転送結果 |
| 変更担当者 | 実行者 |
| 変更日時 | 実行日時 |
一括処理する場合も、最初の1件で変更と通話試験を完了してから、残りへ展開してください。
よくあるエラーと対処方法
| 症状 | 主な原因 | 対処方法 |
|---|---|---|
| コマンドが認識されない | Public Preview対象外、モジュールまたはセッションが未対応 | Frontier参加状況、モジュール、Get-Commandを確認する |
-Identityが見つからない | テンプレートコマンドでは-Idを使う | GetとRemoveは-Id、Auto Attendant取得は-Identityと使い分ける |
Setへパイプしても動かない | -Instanceがパイプライン入力を受けない | 取得オブジェクトを変数に保存して明示的に渡す |
Removeでエラーになる | IDが存在しない、または割り当てが残っている | 全テンプレートと全Auto Attendantを再取得する |
| 一部の割り当て先が見つからない | Auto Attendantが100件を超えている | -First 100と-Skipで全件取得する |
| オペレーター転送にしたのに切断される | Teams Phone Agentにオペレーターが設定されていない | 対象エージェントのOperatorを確認する |
| プロパティ名が資料と一致しない | Preview中の資料とモジュール実装に差がある | Get-Member、Get-Command -Syntax、Get-Helpで実環境を確認する |
| 変更後も旧設定に見える | 再取得していない、反映確認が早すぎる | オブジェクトを再取得し、時間を置いて実通話を試す |
テンプレート系コマンドでは-Idが使われ、Auto Attendantの取得では-Identityが使われます。また、Setの公式例はオブジェクトを変数へ格納して-Instanceに渡す方式です。(Microsoft Learn)
安全な変更・削除のチェックリスト
変更前
- Frontier Public Preview対象テナントである
- 3つのテンプレート管理コマンドを
Get-Commandで確認した - 接続先テナントを確認した
- 対象テンプレートのGUIDを取得した
- テンプレートをCLIXMLまたはJSONで保存した
- 100件単位のページングで全Auto Attendantを取得した
- 対象テンプレートの割り当て先を一覧化した
- オペレーターや転送先の設定を確認した
- 検証用の発信番号と期待結果を決めた
変更後
Getでテンプレートを再取得した- 変更前後の値を比較した
- 通常着信を確認した
- スパム判定時の動作を確認した
- 除外対象番号からの着信を確認した
- オペレーターまたはターゲットへの転送を確認した
- 変更日時、担当者、結果を記録した
削除前
- すべてのTeams Phone Agentから割り当てを外した
- 代替テンプレートへの変更が必要なエージェントを確認した
- 再検索で割り当て件数が0件になった
- 削除対象のGUIDを再確認した
- 削除直前のバックアップを取得した
- 削除後に一覧を再取得して不存在を確認した
まとめ
Teams Phone Agentのスパム検出テンプレートは、Get、Set、Removeの3つのTeams PowerShellコマンドで管理できます。
変更時は、Getで取得したテンプレートオブジェクトのプロパティを編集し、Set -Instanceで反映します。削除時は、対象テンプレートを使用しているTeams Phone Agentを全件調査し、先にSpamDetectionTemplateIdを別テンプレートへ変更するか未設定にします。
最も重要なのは、割り当て状況を確認できないまま削除しないことです。最初に3つのコマンドの存在を確認し、テンプレート一覧をバックアップしたうえで、100件単位のページングを使って全Auto Attendantから参照先を検索してください。参照がゼロになったことを確認できてから、Remove-CsMainlineAttendantSpamDetectionTemplateを実行します。
コメント