📚

Citrix Cloud DaaS を扱うための PowerShell module を作った

2024/01/17に公開

PowerShell

citrix

tech

TL;DR

Citrix Cloud DaaS 用の PowerShell module を作りました
いろいろ工夫したので、そのあたりをメモとして残しておきます
あと、GitHub Copilot がすごい

はじめに

PowerShell で Citrix Cloud の DaaS を操作するためのモジュールを作りました。
といっても自分が必要そうないくつかの REST API を wrap したものなので、REST API 全体からすれば全然カバーされていません。

一応、SDKs and APIs に PowerShell module が提供されているのですが、domain joined な Windows でしか動かないそうので、そうではない環境からでも叩けそうな感じのものを作っています。
ただし、そのせいで OAuth の impersonation が使えないっぽいので、OAuth の client credentials grant での認証となります。

GitHub repos

はこちらです。

使い方とかに関しても en/ja で README に書いてあるので、そちらを参照してください。

ぽいんと

PowerShell のちゃんとしたっぽい module の使い方を目指していろいろ作りこんでみました。

private function 的なやつ

PowerShell の module の中でさまざまな function を定義していくわけですが、その function すべてがユーザに見える必要がない、ということがあります。
で、PowerShell で private みたいな修飾子はないようなので、Export-ModuleMember^[1] というのを使って、逆に public な function (cmdlet) を定義します。

class property

なんでこうしたのかすでに忘れてしまったのですが、ChatGPT とけんけんがくがくやった結果として、Access Token を扱う AccessTokenManager.psm1 では、class property というのを使っています。
ここに $Token として JSON Web Tokens (JWT) を保持してあり、また、その有効期限についても $Expiry として管理しています。
private function もあるのですが、最終的には Get-CitrixAccessToken のみが public function になっています。
また、このファイル名の規則上、規定で読み込まれるファイルにはならないので、Install-Module しても見えず、もろもろの cmdlet から暗黙的に呼ばれる cmdlet となりました。

Citrix.psm1

こちらが Install-Module で読み込まれるメインの module です。
Citrix DaaS REST APIs OpenAPI Specification から REST API の spec がダウンロードできる。
これを VScode で別の tab で開いておけば、GitHub Copilot がほぼほぼ書いてくれるので Get- 系とかは名前を決めて tab 押してるだけで実装ができる、簡単ですね。

`Add-CitrixDeliveryGroupSimpleAccessPolicyIncludedUser`

実装を少し工夫したものとして Add-CitrixDeliveryGroupSimpleAccessPolicyIncludedUser を挙げておきます。
Get-CitrixDeliveryGroup の結果返ってくる delivery group の json ではもろもろ省略しましたが、以下のような感じです。^[2]

DeliveryGroups_GetDeliveryGroup.json

{
  "SimpleAccessPolicy": {
...
    "IncludedUsers": [
      {
        "Domain": "string",
...
        "DisplayName": "string",
        "SamName": "string",
        "SamAccountName": "string",
...
      }
    ],
...
}

一方で、delivery group を修正する DeliveryGroups_PatchDeliveryGroup^[3] では以下のようにユーザーの配列を投げるような感じになっています。

DeliveryGroups_PatchDeliveryGroup.json

{
  "SimpleAccessPolicy": {
...
    "IncludedUsers": [
      "Name of an included user"
    ],
...
}

ということで、全然合致してないので、Get- したものをちょっとこねこねして、Update- するようにしているのが以下の部分です。

Add-CitrixDeliveryGroupSimpleAccessPolicyIncludedUser.ps1

    $response = Get-CitrixDeliveryGroup -DeliveryGroupName $DeliveryGroupName
    $currentIncludedUsers = $response.SimpleAccessPolicy.IncludedUsers | Select-Object -ExpandProperty SamName

    $body = @{
        "SimpleAccessPolicy" = @{
            "IncludedUsers" = $currentIncludedUsers + @($UserName)
        }
    } | ConvertTo-Json

    $response = Invoke-CitrixRestMethod -PartUrl "DeliveryGroups/$DeliveryGroupName" -Method "Patch" -Body $body

まとめ

PowerShell で Citrix Cloud の DaaS を操作するためのモジュールを作りました。
PowerShell module としてもある程度力をかけてというか、それっぽい感じに作ったつもりです。
全然機能は足りていませんが、逆に参考程度には見ていただけるんじゃないかなと思っています。

参考

Citrix Cloud API Walkthrough

まずはこれを読め的なやつ

How to get a site ID in Citrix DaaS

なんか site ID っていう、Web からぽちぽちしてる限りだと意識することのないものがあるので、それを取得する方法が書いてある

How to add a machine to a machine catalog in Citrix DaaS

Citrix DaaS REST API 叩くならこの辺が実装の参考になりそう

Get started with Citrix Cloud APIs

とりあえず OAuth のお作法に沿って client_id と client_secret を取得するところまでの手順が書いてある

Machines_UpdateMachineCatalogMachine

どれでもいいんだけど結局 REST API spec がこの辺なので、読み解きながら実装していけばよい

脚注