StoreFront

StoreFront SDK

October 3, 2023

寄稿者:

Citrix StoreFrontは、多くのMicrosoft Windows PowerShellのバージョン3.0モジュールをベースとしたSDKを提供しています。このSDKにより、StoreFront MMCコンソールと同じタスクだけでなく、コンソールだけでは実行できないタスクも実行できます。

SDKについては、StoreFront SDKを参照してください。

SDKの使用

このSDKは、さまざまなStoreFrontコンポーネントをインストールおよび構成する場合に、インストールウィザードにより自動的にインストールされた多くのPowerShellスナップインで構成されています。

コマンドレットにアクセスして実行するには：

管理者としてPowerShellコマンドラインプロンプトまたはWindows PowerShell ISEを起動します。

StoreFrontのローカルの管理者グループのメンバーを使って、シェルまたはスクリプトを実行する必要があります。
スクリプト内でSDKコマンドレットを使用するには、PowerShell実行ポリシーを設定する必要があります。

PowerShell実行ポリシーについて詳しくは、Microsoft社のドキュメントを参照してください。
Windows PowerShellコンソールでAdd-Moduleコマンドを使って、必要なモジュールをPowerShell環境に追加します。たとえば、次のように入力します：

Import-Module Citrix.StoreFront

すべてのコマンドレットをインポートするには、次のように入力します。

Get-Module -ListAvailable | Where-Object { $_.Name.StartsWith("Citrix.StoreFront") } | Import-Module

インポートが完了すると、各コマンドレットとそのヘルプにアクセスできます。

SDKの導入

スクリプトを作成するには、次の手順を実行します。

StoreFrontによって %ProgramFiles%\Citrix\Receiver StoreFront\PowerShellSDK\Examples フォルダー内にインストールされた、指定のSDKサンプルの一つを実行します。
独自のスクリプトのカスタマイズを容易にするため、サンプルスクリプトをレビューして、各部の実行内容について把握します。詳しくは、スクリプトの実行内容についての詳細を説明している使用例を参照してください。
例のスクリプトをより実際の環境に応じて編集します。これを行うには、以下の手順に従います。
- PowerShell ISEまたは同様のツールを使ってスクリプトを編集します。
- 変数を使って、再使用または変更するための値を割り当てます。
- 不要なコマンドを削除します。
- StoreFrontコマンドレットはプレフィックスSTFにより識別することができます。
- Get-Helpコマンドレットを使って、特定のコマンド上により詳細な情報のためのコマンドレット名および -Fullパラメーターを指定します。

例

注：

SDKに拡張や修正が追加されていることがあるため、例のスクリプトをコピーして貼り付けるのではなく、説明されている手順を実際に実行することをお勧めします。

例	説明
簡素な展開の作成	スクリプト：単一のXenDesktopサーバーで構成されたStoreFront Controllerのある簡素な展開を作成します。
リモートアクセス展開の作成	スクリプト：以前のスクリプト上に構築して、展開にリモートアクセスを追加します。
最適な起動ゲートウェイがあるリモートアクセス展開の作成	スクリプト：以前のスクリプト上に構築して、ユーザーエクスペリエンスをより良いものに吸うため、優先する最適な起動ゲートウェイを追加します。

例：簡素な展開の作成

次の例では、1つのXenDesktop Controllerで構成された簡素な展開の作成方法を示します。

まず、「SDKの導入」で説明されている手順を実行しておく必要があります。StoreFront展開を自動化するスクリプトの作成について説明した手法を使って、この例をカスタマイズできます。

注：

SDKに拡張や修正が追加されていることがあるため、このドキュメントのスクリプト例をコピーして貼り付けるのではなく、このドキュメントで説明されている手順を実際に実行することをお勧めします。

スクリプトの理解

ここでは、StoreFrontにより生成されるスクリプトの各部で何を実行しているかについて説明します。これを理解することで、スクリプトを目的に応じてカスタマイズできるようになります。

エラー処理要件を設定し、必要なStoreFrontモジュールをインポートします。より新しいバージョンのPowerShellではインポートの必要はありません。

 Param(
     [Parameter(Mandatory=$true)]
     [Uri]$HostbaseUrl,
     [long]$SiteId = 1,
     [ValidateSet("XenDesktop","XenApp","AppController","VDIinaBox")]
     [string]$Farmtype = "XenDesktop",
     [Parameter(Mandatory=$true)]
     [string[]]$FarmServers,
     [string]$StoreVirtualPath = "/Citrix/Store",
     [bool]$LoadbalanceServers = $false,
     [int]$Port = 80,
     [int]$SSLRelayPort = 443,
     [ValidateSet("HTTP","HTTPS","SSL")]
     [string]$TransportType = "HTTP"
     )
     # Import StoreFront modules. Required for versions of PowerShell earlier than 3.0 that do not support autoloading
     Import-Module Citrix.StoreFront
     Import-Module Citrix.StoreFront.Stores
     Import-Module Citrix.StoreFront.Authentication
     Import-Module Citrix.StoreFront.WebReceiver
 <!--NeedCopy-->

指定の $StoreVirtualPathをベースとして認証およびCitrix Receiver for Webサービスの仮想パスを自動化します。仮想パスは常にIISのパスであるため、$StoreVirtualPathは$StoreIISpathと同じです。したがってPowershellでは、「/Citrix/Store」、「/Citrix/StoreWeb」または「/Citrix/StoreAuth」のような値が使用されます。
```
 # Determine the Authentication and Receiver virtual path to use based of the Store
 $authenticationVirtualPath = "$($StoreIISPath.TrimEnd('/'))Auth"
 $receiverVirtualPath = "$($StoreVirtualPath.TrimEnd('/'))Web"
 
```

必要なStoreFrontサービスの追加準備に備えて新しい展開を作成します（まだ存在していない場合）。-Confirm:$falseは、展開を進めることができることを確認する要件を無効にします。

 # Determine if the deployment already exists
 $existingDeployment = Get-STFDeployment
 if(-not $existingDeployment)
 {
     # Install the required StoreFront components
     Add-STFDeployment -HostBaseUrl $HostbaseUrl -SiteId $SiteId -Confirm:$false
 }
 elseif($existingDeployment.HostbaseUrl -eq $HostbaseUrl)
 {
     # The deployment exists but it is configured to the desired hostbase url
     Write-Output "A deployment has already been created with the specified hostbase url on this server and will be used."
 }
 else
 {
     Write-Error "A deployment has already been created on this server with a different host base url."
 }
 <!--NeedCopy-->

新しい認証サービスを指定された仮想パスで作成します（パスに認証サービスが存在しない場合）。ユーザー名とパスワードを使ったデフォルトの認証方法が有効です。

 # Determine if the authentication service at the specified virtual path exists
 $authentication = Get-STFAuthenticationService -VirtualPath $authenticationVirtualPath
 if(-not $authentication)
 {
     # Add an Authentication service using the IIS path of the Store appended with Auth
     $authentication = Add-STFAuthenticationService $authenticationVirtualPath
 }
 else
 {
     Write-Output "An Authentication service already exists at the specified virtual path and will be used."
 }
 <!--NeedCopy-->

指定された仮想パスで、配列 $XenDesktopServersで定義されたサーバーがある1つのXenDesktop Controllerで構成された新しいストアサービスを作成します（まだ存在していない場合）。

 # Determine if the store service at the specified virtual path exists
 $store = Get-STFStoreService -VirtualPath $StoreVirtualPath
 if(-not $store)
 {
 # Add a Store that uses the new Authentication service configured to publish resources from the supplied servers
 $store = Add-STFStoreService -VirtualPath $StoreVirtualPath -AuthenticationService $authentication -FarmName $Farmtype -FarmType $Farmtype -Servers $FarmServers -LoadBalance $LoadbalanceServers `
         -Port $Port -SSLRelayPort $SSLRelayPort -TransportType $TransportType
 }
 else
 {
     Write-Output "A Store service already exists at the specified virtual path and will be used. Farm and servers will be appended to this store."
     # Get the number of farms configured in the store
     $farmCount = (Get-STFStoreFarmConfiguration $store).Farms.Count
     # Append the farm to the store with a unique name
     Add-STFStoreFarm -StoreService $store -FarmName "Controller$($farmCount + 1)" -FarmType $Farmtype -Servers $FarmServers -LoadBalance $LoadbalanceServers -Port $Port `
         -SSLRelayPort $SSLRelayPort -TransportType $TransportType
 }
 <!--NeedCopy-->

指定のIIS仮想パスでCitrix Receiver for Webサービスを追加して、上記で作成されたストアで公開されたアプリケーションにアクセスします。

 # Determine if the receiver service at the specified virtual path exists
 $receiver = Get-STFWebReceiverService -VirtualPath $receiverVirtualPath
 if(-not $receiver)
 {
     # Add a Receiver for Web site so users can access the applications and desktops in the published in the Store
     $receiver = Add-STFWebReceiverService -VirtualPath $receiverVirtualPath -StoreService $store
 }
 else
 {
     Write-Output "A Web Receiver service already exists at the specified virtual path and will be used."
 }
 <!--NeedCopy-->

ストアに対してXenAppサービスを有効にして、古いCitrix ReceiverまたはCitrix Workspaceアプリクライアントは公開アプリケーションに接続できます。

 # Determine if PNA is configured for the Store service
 $storePnaSettings = Get-STFStorePna -StoreService $store
 if(-not $storePnaSettings.PnaEnabled)
 {
 # Enable XenApp services on the store and make it the default for this server
 Enable-STFStorePna -StoreService $store -AllowUserPasswordChange -DefaultPnaService
 }
 <!--NeedCopy-->

例：リモートアクセス展開の作成

次の例は以前のスクリプト上に構築して、リモートアクセスのある展開を追加します。

まず、「 SDKの導入」で説明されている手順を実行しておく必要があります。StoreFront展開を自動化するスクリプトの作成について説明した手法を使って、この例をカスタマイズできます。

注：

SDKに拡張や修正が追加されていることがあるため、このドキュメントのスクリプト例をコピーして貼り付けるのではなく、このドキュメントで説明されている手順を実際に実行することをお勧めします。

スクリプトの理解

エラー処理要件を設定し、必要なStoreFrontモジュールをインポートします。より新しいバージョンのPowerShellではインポートの必要はありません。

 Param(
     [Parameter(Mandatory=$true)]
     [Uri]$HostbaseUrl,
     [Parameter(Mandatory=$true)]
     [long]$SiteId = 1,
     [string]$Farmtype = "XenDesktop",
     [Parameter(Mandatory=$true)]
     [string[]]$FarmServers,
     [string]$StoreVirtualPath = "/Citrix/Store",
     [bool]$LoadbalanceServers = $false,
     [int]$Port = 80,
     [int]$SSLRelayPort = 443,
     [ValidateSet("HTTP","HTTPS","SSL")]
     [string]$TransportType = "HTTP",
     [Parameter(Mandatory=$true)]
     [Uri]$GatewayUrl,
     [Parameter(Mandatory=$true)]
     [Uri]$GatewayCallbackUrl,
     [Parameter(Mandatory=$true)]
     [string[]]$GatewaySTAUrls,
     [string]$GatewaySubnetIP,
     [Parameter(Mandatory=$true)]
     [string]$GatewayName
 )
 Set-StrictMode -Version 2.0

 # Any failure is a terminating failure.
 $ErrorActionPreference = 'Stop'
 $ReportErrorShowStackTrace = $true
 $ReportErrorShowInnerException = $true
 # Import StoreFront modules. Required for versions of PowerShell earlier than 3.0 that do not support autoloading
 Import-Module Citrix.StoreFront
 Import-Module Citrix.StoreFront.Stores
 Import-Module Citrix.StoreFront.Roaming
 <!--NeedCopy-->

以前のサンプルスクリプトを呼び出して、内部アクセスのStoreFront展開を作成します。ベース展開が拡張され、リモートアクセスがサポートされます。

 # Create a simple deployment by invoking the SimpleDeployment example
 $scriptDirectory = Split-Path -Path $MyInvocation.MyCommand.Definition -Parent
 $scriptPath = Join-Path $scriptDirectory "SimpleDeployment.ps1"
 & $scriptPath -HostbaseUrl $HostbaseUrl -SiteId $SiteId -FarmServers $FarmServers -StoreVirtualPath $StoreVirtualPath -Farmtype $Farmtype `
     -LoadbalanceServers $LoadbalanceServers -Port $Port  -SSLRelayPort $SSLRelayPort -TransportType $TransportType
 <!--NeedCopy-->

リモートアクセスがサポートされるように更新する必要があるため、簡素な展開で作成されたサービスを取得します。

 # Determine the Authentication and Receiver sites based on the Store
 $store = Get-STFStoreService -VirtualPath $StoreVirtualPath
 $authentication = Get-STFAuthenticationService -StoreService $store
 $receiverForWeb = Get-STFWebReceiverService -StoreService $store
 <!--NeedCopy-->

Citrix Gatewayを使用したリモートアクセスで必要なCitrix Receiver for Webサービス上で、CitrixAGBasicを有効にします。サポートされているプロトコルからCitrix Receiver for WebのCitrixAGBasicおよびExplicitForms認証方法を取得します。

 # Get the Citrix Receiver for Web CitrixAGBasic and ExplicitForms authentication method from the supported protocols
 # Included for demonstration purposes as the protocol name can be used directly if known
 $receiverMethods = Get-STFWebReceiverAuthenticationMethodsAvailable | Where-Object { $_ -match "Explicit" -or $_ -match "CitrixAG" }
 # Enable CitrixAGBasic in Receiver for Web (required for remote access)
 Set-STFWebReceiverService $receiverForWeb -AuthenticationMethods $receiverMethods
 <!--NeedCopy-->

認証サービスでCitrixAGBasicを有効にします。これはリモートアクセスで必要です。

 # Get the CitrixAGBasic authentication method from the protocols installed.
 # Included for demonstration purposes as the protocol name can be used directly if known
 $citrixAGBasic = Get-STFAuthenticationProtocolsAvailable | Where-Object { $_ -match "CitrixAGBasic" }
 # Enable CitrixAGBasic in the Authentication service (required for remote access)
 Enable-STFAuthenticationServiceProtocol -AuthenticationService $authentication -Name $citrixAGBasic
 <!--NeedCopy-->

新しいリモートアクセスゲートウェイを、オプションのサブネットIPアドレスを指定して追加し、リモートでアクセスするストアに登録します。

 # Add a new Gateway used to access the new store remotely
 Add-STFRoamingGateway -Name "NetScaler10x" -LogonType Domain -Version Version10_0_69_4 -GatewayUrl $GatewayUrl '
 -CallbackUrl $GatewayCallbackUrl -SecureTicketAuthorityUrls $GatewaySTAUrls
 # Get the new Gateway from the configuration (Add-STFRoamingGateway will return the new Gateway if -PassThru is supplied as a parameter)
 $gateway = Get-STFRoamingGateway -Name $GatewayName
 # If the gateway subnet was provided then set it on the gateway object
 if($GatewaySubnetIP)
 {
     Set-STFRoamingGateway -Gateway $gateway -SubnetIPAddress $GatewaySubnetIP
 }
 # Register the Gateway with the new Store
 Register-STFStoreGateway -Gateway $gateway -StoreService $store -DefaultGateway
 <!--NeedCopy-->

例：最適な起動ゲートウェイがあるリモートアクセス展開の作成

次の例は以前のスクリプト上に構築して、オプションの起動ゲートウェイリモートアクセスのある展開を追加します。

まず、「 SDKの導入」で説明されている手順を実行しておく必要があります。StoreFront展開を自動化するスクリプトの作成について説明した手法を使って、この例をカスタマイズできます。

注：

SDKに拡張や修正が追加されていることがあるため、このドキュメントのスクリプト例をコピーして貼り付けるのではなく、このドキュメントで説明されている手順を実際に実行することをお勧めします。

スクリプトの理解

エラー処理要件を設定し、必要なStoreFrontモジュールをインポートします。より新しいバージョンのPowerShellではインポートの必要はありません。

 Param(
     [Parameter(Mandatory=$true)]
     [Uri]$HostbaseUrl,
     [long]$SiteId = 1,
     [string]$Farmtype = "XenDesktop",
     [Parameter(Mandatory=$true)]
     [string[]]$FarmServers,
     [string]$StoreVirtualPath = "/Citrix/Store",
     [bool]$LoadbalanceServers = $false,
     [int]$Port = 80,
     [int]$SSLRelayPort = 443,
     [ValidateSet("HTTP","HTTPS","SSL")]
     [string]$TransportType = "HTTP",
     [Parameter(Mandatory=$true)]
     [Uri]$GatewayUrl,
     [Parameter(Mandatory=$true)]
     [Uri]$GatewayCallbackUrl,
     [Parameter(Mandatory=$true)]
     [string[]]$GatewaySTAUrls,
     [string]$GatewaySubnetIP,
     [Parameter(Mandatory=$true)]
     [string]$GatewayName,
     [Parameter(Mandatory=$true)]
     [Uri]$OptimalGatewayUrl,
     [Parameter(Mandatory=$true)]
     [string[]]$OptimalGatewaySTAUrls,
     [Parameter(Mandatory=$true)]
     [string]$OptimalGatewayName
 )
 Set-StrictMode -Version 2.0
 # Any failure is a terminating failure.
 $ErrorActionPreference = 'Stop'
 $ReportErrorShowStackTrace = $true
 $ReportErrorShowInnerException = $true
 # Import StoreFront modules. Required for versions of PowerShell earlier than 3.0 that do not support autoloading
 Import-Module Citrix.StoreFront
 Import-Module Citrix.StoreFront.Stores
 Import-Module Citrix.StoreFront.Roaming
 <!--NeedCopy-->

リモートアクセス展開スクリプト内に呼び出し、基本展開を構成し、リモートアクセスを追加します。

 # Create a remote access deployment
 $scriptDirectory = Split-Path -Path $MyInvocation.MyCommand.Definition -Parent
 $scriptPath = Join-Path $scriptDirectory "RemoteAccessDeployment.ps1"
 & $scriptPath -HostbaseUrl $HostbaseUrl -SiteId $SiteId -FarmServers $FarmServers -StoreVirtualPath $StoreVirtualPath -Farmtype $Farmtype `
     -LoadbalanceServers $LoadbalanceServers -Port $Port  -SSLRelayPort $SSLRelayPort -TransportType $TransportType `
     -GatewayUrl $GatewayUrl -GatewayCallbackUrl $GatewayCallbackUrl -GatewaySTAUrls $GatewaySTAUrls -GatewayName $GatewayName
 <!--NeedCopy-->

優先的で最適な起動ゲートウェイを追加し、構成済みゲートウェイの一覧からそれを取得します。

 # Add a new Gateway used for remote HDX access to desktops and apps
 $gateway = Add-STFRoamingGateway -Name $OptimalGatewayName -LogonType UsedForHDXOnly -GatewayUrl $OptimalGatewayUrl -SecureTicketAuthorityUrls $OptimalGatewaySTAUrls -PassThru
 <!--NeedCopy-->

最適なゲートウェイを使用するためにストアサービスを取得し、ゲートウェイをファームからの起動に割り当てて登録します。

 # Get the Store configured by SimpleDeployment.ps1
 $store = Get-STFStoreService -VirtualPath $StoreVirtualPath
 # Register the Gateway with the new Store for launch against all of the farms (currently just one)
 $farmNames = @($store.FarmsConfiguration.Farms | foreach { $_.FarmName })
 Register-STFStoreOptimalLaunchGateway -Gateway $gateway -StoreService $store -FarmName $farmNames
 <!--NeedCopy-->

例： SAML認証用にIDプロバイダーとサービスプロバイダー（StoreFront）間でメタデータを交換する

SAML認証は、StoreFront管理コンソールで構成できます（「認証サービスの構成」を参照するか、以下のPowerShellコマンドレットを使用します：

Export-STFSamlEncryptionCertificate
Export-STFSamlSigningCertificate
Import-STFSamlEncryptionCertificate
Import-STFSamlSigningCertificate
New-STFSamlEncryptionCertificate
New-STFSamlIdPCertificate
New-STFSamlSigningCertificate

Update-STFSamlIdPFromMetadataコマンドレットを使用すると、IDプロバイダーとサービスプロバイダー（今回はStoreFront）の間でメタデータ（ID、証明書、エンドポイントなどの構成）を交換できます。

StoreFrontストアの名前が「Store」であり、専用の認証サービスが設定されている場合、そのメタデータエンドポイントは次のようになります。

https://<storefront host>/Citrix/StoreAuth/SamlForms/ServiceProvider/Metadata

IDプロバイダーでメタデータのインポートがサポートされている場合、このプロバイダーを上記URLへポイントすることができます。注：この操作はHTTPSを介して行う必要があります。

StoreFrontでIDプロバイダーのメタデータを消費するには、次のPowerShellコマンドレットを使用します。

Get-Module "Citrix.StoreFront*" -ListAvailable | Import-Module

# Remember to change this with the virtual path of your Store.
$StoreVirtualPath = "/Citrix/Store"

$store = Get-STFStoreService -VirtualPath $StoreVirtualPath
$auth = Get-STFAuthenticationService -StoreService $store

# To read the metadata directly from the Identity Provider, use the following:
# Note again this is only allowed for https endpoints
Update-STFSamlIdPFromMetadata -AuthenticationService $auth -Url https://example.com/FederationMetadata/2007-06/FederationMetadata.xml

# If the metadata has already been download, use the following:
# Note: Ensure that the file is encoded as UTF-8
Update-STFSamlIdPFromMetadata -AuthenticationService $auth -FilePath "C:\Users\exampleusername\Downloads\FederationMetadata.xml"
<!--NeedCopy-->

例：SAML認証用の指定されたストアのメタデータおよびACSエンドポイント一覧を作成する

次のスクリプトを使用して、指定されたストアのメタデータおよびACS（Assertion Consumer Service）エンドポイントの一覧を作成できます。

# Change this value for your Store
$storeVirtualPath = "/Citrix/Store"

$auth = Get-STFAuthenticationService -Store (Get-STFStoreService -VirtualPath $storeVirtualPath)
$spId = $auth.AuthenticationSettings["samlForms"].SamlSettings.ServiceProvider.Uri.AbsoluteUri
$acs = New-Object System.Uri $auth.Routing.HostbaseUrl, ($auth.VirtualPath + "/SamlForms/AssertionConsumerService")
$md = New-Object System.Uri $auth.Routing.HostbaseUrl, ($auth.VirtualPath + "/SamlForms/ServiceProvider/Metadata")
$samlTest = New-Object System.Uri $auth.Routing.HostbaseUrl, ($auth.VirtualPath + "/SamlTest")
Write-Host "SAML Service Provider information:
Service Provider ID: $spId
Assertion Consumer Service: $acs
Metadata: $md
Test Page: $samlTest"
<!--NeedCopy-->

出力例：

SAML Service Provider information:
Service Provider ID: https://storefront.example.com/Citrix/StoreAuth
Assertion Consumer Service: https://storefront.example.com/Citrix/StoreAuth/SamlForms/AssertionConsumerService
Metadata: https://storefront.example.com/Citrix/StoreAuth/SamlForms/ServiceProvider/Metadata
Test Page: https://storefront.example.com/Citrix/StoreAuth/SamlTest
<!--NeedCopy-->

このコンテンツの正式なバージョンは英語で提供されています。Cloud Software Groupドキュメントのコンテンツの一部は、お客様の利便性のみを目的として機械翻訳されています。Cloud Software Groupは機械翻訳されたコンテンツを管理していないため、誤り、不正確な情報、不適切な用語が含まれる場合があります。英語の原文から他言語への翻訳について、精度、信頼性、適合性、正確性、またはお使いのCloud Software Group製品またはサービスと機械翻訳されたコンテンツとの整合性に関する保証、該当するライセンス契約書またはサービス利用規約、あるいはCloud Software Groupとのその他すべての契約に基づき提供される保証、および製品またはサービスのドキュメントとの一致に関する保証は、明示的か黙示的かを問わず、かかるドキュメントの機械翻訳された範囲には適用されないものとします。機械翻訳されたコンテンツの使用に起因する損害または問題について、Cloud Software Groupは責任を負わないものとします。

この情報は役に立ちましたか?

StoreFront SDK

October 3, 2023

寄稿者:

October 3, 2023

寄稿者:

この情報は役に立ちましたか?