Automation Cloudのプラットフォーム管理APIのPowerShellサンプルスクリプト集

# はじめに
- ここではUiPath Automation Cloudのプラットフォーム管理APIのリクエスト送信の実例として、Powershellスクリプト集を公開します。リクエスト送信には[Invoke-RestMethod](https://learn.microsoft.com/ja-jp/powershell/module/microsoft.powershell.utility/invoke-restmethod?view=powershell-7.4)を使用します。
- プラットフォーム管理APIについては以下の参考リンクに詳細な説明がありますので、そちらをご参照ください

https://qiita.com/HirotakaTakehana/items/94d947b4b87d21c85ce5



## 免責事項

- ここでご紹介するサンプルスクリプトはChatGPT等を利用して自動生成されたものをベースにしております。あくまで動作確認用として提示おり、本番環境での動作を保証するものではありませんで予めご了承ください
-  本記事は2025年1月時点での情報を掲載しております
-  現時点でプラットフォーム管理APIはプレビュー機能として公開されています。今後の仕様変更で動作しなくなる場合がある点についてもご了承ください
-  本記事で記載しているPowershellスクリプトの構文に関するサポート等は受け付けていないため、Powershellのガイドをご参照ください


# 外部アプリケーションの追加
本稿のスクリプト例では、アクセストークンの取得にUiPath Automation Cloudの[外部アプリケーション](https://docs.uipath.com/ja/automation-cloud/automation-cloud/latest/api-guide/accessing-uipath-resources-using-external-applications)を使用します。認可はクライアント資格情報を使用します。

スクリプトを実行する前に、事前にAutomation Cloudの管理画面において外部アプリケーショを追加の上、アプリケーションIDとアプリケーションシークレットを取得しておく必要があります。
詳細については以下の記事をご参照ください。

https://qiita.com/HirotakaTakehana/items/94d947b4b87d21c85ce5

# スクリプト集

監査ログの取得とグループ操作を例に、サンプルスクリプトを以下に記載します。アクセストークンを取得する処理やパラメータの内容は各スクリプトでほとんど同じですが、簡単のためにそのまま記載しています。

## 監査ログ

###  監査ログをCSV形式でダウンロードする

Automation Cloudの監査ログをダウンロードし、AuditLogs.csvに保存します。
次のスコープが必要です。
- PM.Audit または PM.Audit.Read

``` DownloadAuditLogs.ps1
param (
  [string] $organizationId = "{organizationName}",
  [string] $clientId = "{applicationId}",
  [string] $clientSecret = "{applicationSecret}",
  [string] $partitionGlobalId = "{partitionGlobalIsd}",
  [string] $scopes = "PM.Audit"
)

# Get Access Token Function
function Get-BearerToken {
    $Body = @{
       "client_id" = $clientId
       "client_secret" = $clientSecret
       "scope" = $scopes
       "grant_type" = "client_credentials"
    }
    $tokenEndpoint = "https://cloud.uipath.com/identity_/connect/token"
    $response = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $Body -ContentType "application/x-www-form-urlencoded"
    return $response.access_token
}

# Download Audit Logs Function
function Invoke-DownloadAuditLogsAPI {
    param (
        [string] $bearerToken
    )
    $DownloadAuditLogsEndpoint = "https://cloud.uipath.com/$organizationId/audit_/api/auditlogs/download"
    $headers = @{
        "Authorization" = "Bearer $bearerToken"
		"Content-Type" = "application/json"
    }
    $response = Invoke-RestMethod -Uri $DownloadAuditLogsEndpoint -Method Get -Headers $headers
    return $response
}

# Call token request
$bearerToken = Get-BearerToken

# Call download audit logs request
$AuditResult = Invoke-DownloadAuditLogsAPI -bearerToken $bearerToken
$AuditResult | Out-File -FilePath "AuditLogs.csv"
```


## グループ

### すべてのグループを取得してCSV形式で保存する

次のスコープが必要です。
- PM.Group または PM.Group.Read

このリクエストからのレスポンスにはグループに所属しているメンバー一覧が取得できないようなので、CSVファイルへの出力から除外しています。
グループに所属しているメンバー一覧の取得が必要な場合は後述の[特定のグループを取得する](###特定のグループを取得する)をご利用ください。

``` GetGroupList.ps1
param (
  [string] $organizationId = "{organizationName}",
  [string] $clientId = "{applicationId}",
  [string] $clientSecret = "{applicationSecret}",
  [string] $partitionGlobalId = "{partitionGlobalIsd}",
  [string] $scopes = "PM.Group.Read"
)

# Get Access Token Function
function Get-BearerToken {
    $Body = @{
       "client_id" = $clientId
       "client_secret" = $clientSecret
       "scope" = $scopes
       "grant_type" = "client_credentials"
    }
    $tokenEndpoint = "https://cloud.uipath.com/identity_/connect/token"
    $response = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $Body -ContentType "application/x-www-form-urlencoded"
    return $response.access_token
}

# Get Group List Function
function Invoke-GetGroupAPI {
    param (
        [string] $bearerToken
    )
    $groupEndpoint = "https://cloud.uipath.com/$organizationId/identity_/api/Group/$partitionGlobalId"
    $headers = @{
        "Authorization" = "Bearer $bearerToken"
		"Content-Type" = "application/json"
    }
    $response = Invoke-RestMethod -Uri $groupEndpoint -Method Get -Headers $headers
    return $response
}

# Call token request
$bearerToken = Get-BearerToken

# Call group request
$groupResult = Invoke-GetGroupAPI -bearerToken $bearerToken
Write-Host $groupResult

# Export group list to csv
$csvData = $groupResult | ForEach-Object {
	$item = $_
	[PSCustomObject]@{
		"id" = $item.id
		"name" = $item.name
		"displayName" = $item.displayName
		"type" = $item.type
		"creationTime" = $item.creationTime
		"lastModificationTime" = $item.lastModificationTime
	}
}
$csvData | Export-Csv -Path "GroupResult.csv" -NoTypeInformation
```

### 特定のグループを取得する

特定のグループの情報を取得し、レスポンス本文をテキストファイルに出力します。入力値の```groupId```は前述の[すべてのグループを取得してCSV形式で保存する](###すべてのグループを取得してCSV形式で保存する)で取得する```Id```に相当します。


``` GetSpecificGroup.ps1
param (
  [string] $organizationId = "{organizationName}",
  [string] $clientId = "{applicationId}",
  [string] $clientSecret = "{applicationSecret}",
  [string] $partitionGlobalId = "{partitionGlobalIsd}",
  [string] $scopes = "PM.Group.Read",
  [string] $groupId = "{groupId}"
)

# Get Access Token Function
function Get-BearerToken {
    $Body = @{
       "client_id" = $clientId
       "client_secret" = $clientSecret
       "scope" = $scopes
       "grant_type" = "client_credentials"
    }
    $tokenEndpoint = "https://cloud.uipath.com/identity_/connect/token"
    $response = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $Body -ContentType "application/x-www-form-urlencoded"
    return $response.access_token
}

# Get Specific Group Function
function Invoke-GetGroupAPI {
    param (
        [string] $bearerToken
    )
    $groupEndpoint = "https://cloud.uipath.com/$organizationId/identity_/api/Group/$partitionGlobalId/$groupId"
    $headers = @{
        "Authorization" = "Bearer $bearerToken"
		"Content-Type" = "application/json"
    }
    $response = Invoke-RestMethod -Uri $groupEndpoint -Method Get -Headers $headers
    return $response | ConvertTo-Json
}

# Call token request
$bearerToken = Get-BearerToken

# Call group request
$groupResult = Invoke-GetGroupAPI -bearerToken $bearerToken

# Export result to text file
$groupResult | Out-File -FilePath "SpecificGroupResult.txt"
```



### 特定のグループを削除する

特定のグループを削除します。入力値の```groupId```は前述の[すべてのグループを取得してCSV形式で保存する](###すべてのグループを取得してCSV形式で保存する)で取得する```Id```に相当します。尚、削除できるのは管理者等が作成したグループのみで、既定のグループ(Automation Developers等)は削除できません。
このリクエストのレスポンスには本文が返らないため、代わりにステータスコードを出力しています。

``` AC_DeleteGroup.ps1
param (
  [string] $organizationId = "{organizationName}",
  [string] $clientId = "{applicationId}",
  [string] $clientSecret = "{applicationSecret}",
  [string] $partitionGlobalId = "{partitionGlobalIsd}",
  [string] $scopes = "PM.Group.Read",
  [string] $groupId = "{groupId}"
)

# Get Access Token Function
function Get-BearerToken {
    $Body = @{
       "client_id" = $clientId
       "client_secret" = $clientSecret
       "scope" = $scopes
       "grant_type" = "client_credentials"
    }
    $tokenEndpoint = "https://cloud.uipath.com/identity_/connect/token"
    $response = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $Body -ContentType "application/x-www-form-urlencoded"
    return $response.access_token
}

# Delete Group Function
function Invoke-DeleteGroupAPI {
    param (
        [string] $bearerToken
    )
    $groupEndpoint = "https://cloud.uipath.com/$organizationId/identity_/api/Group/$partitionGlobalId/$groupId"
    $headers = @{
        "Authorization" = "Bearer $bearerToken"
		"Content-Type" = "application/json"
    }
    Invoke-RestMethod -Uri $groupEndpoint -Method Delete -Headers $headers -StatusCodeVariable statusCode
    return $statusCode
}

# Call token request
$bearerToken = Get-BearerToken

# Call group request
$statusCode = Invoke-DeleteGroupAPI -bearerToken $bearerToken
Write-Host "Status Code: $statusCode"
```

# ユーザー

## すべてのローカルユーザーを取得して保存する

次のスコープが必要です。

PM.User または PM.User.Read

Automation Cloudの組織に招待されているローカルユーザーの一覧を取得し、レスポンス本文をテキストファイルに出力します。

``` AC_GetLocalUsers.ps1
param (
  [string] $organizationId = "{organizationName}",
  [string] $clientId = "{applicationId}",
  [string] $clientSecret = "{applicationSecret}",
  [string] $partitionGlobalId = "{partitionGlobalId}",
  [string] $scopes = "PM.User.Read"
)

# Get Access Token Function
function Get-BearerToken {
    $Body = @{
       "client_id" = $clientId
       "client_secret" = $clientSecret
       "scope" = $scopes
       "grant_type" = "client_credentials"
    }
    $tokenEndpoint = "https://cloud.uipath.com/identity_/connect/token"
    $response = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $Body -ContentType "application/x-www-form-urlencoded"
    return $response.access_token
}

# Get User List Function
function Invoke-GetUserAPI {
    param (
        [string] $bearerToken
    )
    $endpoint = "https://cloud.uipath.com/$organizationId/identity_/api/User/users/$partitionGlobalId"
    $headers = @{
        "Authorization" = "Bearer $bearerToken"
        "Content-Type" = "application/json"
    }
    $response = Invoke-RestMethod -Uri $endpoint -Method Get -Headers $headers
    return $response | ConvertTo-Json
}

# Call token request
$bearerToken = Get-BearerToken

# Call User Request
$result = Invoke-GetUserAPI -bearerToken $bearerToken

# Save Result as Json File
$result | Out-File -FilePath "UserResult.json" -Encoding UTF8
```

# 設定

## 設定を取得する

以下のスコープが必要です。

PM.Setting または PM.Setting.Read

メールおよび認証の設定のキーと値のペアのリストを取得します。

https://docs.uipath.com/ja/orchestrator/standalone/2024.10/api-guide/get-settings

``` AC_GetSetting.ps1
param (
  [string] $organizationId = "{organizationName}",
  [string] $clientId = "{applicationId}",
  [string] $clientSecret = "{applicationSecret}",
  [string] $partitionGlobalId = "{partitionGlobalId}",
  [string] $scopes = "PM.Setting.Read"
)

# Get Access Token Function
function Get-BearerToken {
    $Body = @{
       "client_id" = $clientId
       "client_secret" = $clientSecret
       "scope" = $scopes
       "grant_type" = "client_credentials"
    }
    $tokenEndpoint = "https://cloud.uipath.com/identity_/connect/token"
    $response = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $Body -ContentType "application/x-www-form-urlencoded"
    return $response.access_token
}

# Get Setting Function
function Invoke-GetSettingAPI {
    param (
        [string] $bearerToken
    )
    $endpoint = "https://cloud.uipath.com/identity_/api/Setting?partitionGlobalId=$partitionGlobalId"
    $headers = @{
        "Authorization" = "Bearer $bearerToken"
        "Content-Type" = "application/json"
    }
    $response = Invoke-RestMethod -Uri $endpoint -Method Get -Headers $headers 
    return $response | ConvertTo-Json
}

# Call Token Request
$bearerToken = Get-BearerToken
Write-Host $bearerToken

# Call Setting Request
$result = Invoke-GetSettingAPI -bearerToken $bearerToken

# Save Result as Json File
$result | Out-File -FilePath "SettingResult.json" -Encoding UTF8
```


# 補足

## partitionGlobalIdの取得方法
プラットフォーム管理APIの実行に必要なpartitionGlobalIdの取得方法については [Automation Cloudのプラットフォーム管理APIが必要とするpartitionGlobalIdの取得方法](https://forum.uipath.com/t/automation-cloud-api-partitionglobalid/712887) をご参照ください。


# おわりに

本記事ではAutomation Cloudのプラットフォーム管理APIを利用するためのPowershellサンプルスクリプトをご紹介しました。追加で動作確認できたものがあれば随時更新予定です。