Amazon IVSのPlayback Restriction PolicyをAWS CLIから操作してみた

AWS CLIを使ってIVS Low-Latency StreamingのPlayback Restriction Policyを操作してみます。シンプルな操作体系ですが、国コードなどの書式指定の方法だけ注意しておきましょう。
2024.02.02

はじめに

清水です。昨日(2024/02/01)のエントリでAWSのマネージド型ライブストリーミングソリューションであるAmazon Interactive Video Service (Amazon IVS)のLow-Latency Streamingでポリシーによる再生制限ができるPlayback restriction policiesが利用可能になったアップデートについてお届けしました。

What's New at AWSでもアップデート情報が2024/02/01付でポストされていますね。

このIVS Low-Latency StreamingのPlayback Restriction Policy、アップデートブログではAWSマネジメントコンソールからの操作を紹介しましたが、AWS CLIをはじめとしたAPIでももちろんサポートされています。本エントリではAWS CLIを使ってPlayback Restriction Policyの操作をしてみたのでまとめてみたいと思います。

本エントリでのAWS CLIの環境について

残念なことに、本検証を行った2024/02/02 19:00の時点でAWS CLI v2ではPlayback Restriction Policy関連のAPIが未対応なようでした。

CloudShellのデフォルトのAWS CLI環境(バージョンは2.15.15でした)でPlayback Restriction Policyの一覧表示コマンドを実行すると、以下のようにコマンドが見つからない旨、表示されてしまいます。

[cloudshell-user@ip-10-130-54-157 ~]$ aws --version
aws-cli/2.15.15 Python/3.11.6 Linux/6.1.66-91.160.amzn2023.x86_64 exec-env/CloudShell exe/x86_64.amzn.2023 prompt/off
[cloudshell-user@ip-10-130-54-157 ~]$ aws ivs list-playback-restriction-policies

usage: aws [options] <command> <subcommand> [<subcommand> ...] [parameters]
To see help text, you can run:

  aws help
  aws <command> help
  aws <command> <subcommand> help

aws: error: argument operation: Invalid choice, valid choices are:

batch-get-channel                        | batch-get-stream-key                    
batch-start-viewer-session-revocation    | create-channel                          
create-recording-configuration           | create-stream-key                       
delete-channel                           | delete-playback-key-pair                
delete-recording-configuration           | delete-stream-key                       
get-channel                              | get-playback-key-pair                   
get-recording-configuration              | get-stream                              
get-stream-key                           | get-stream-session                      
import-playback-key-pair                 | list-channels                           
list-playback-key-pairs                  | list-recording-configurations           
list-stream-keys                         | list-stream-sessions                    
list-streams                             | list-tags-for-resource                  
put-metadata                             | start-viewer-session-revocation         
stop-stream                              | tag-resource                            
untag-resource                           | update-channel                          
help

手元のMacでAWS CLI v2環境を最新版にしたところバージョンが2.15.16にはなりましたが、やはりPlayback Restriction Policyのコマンドは見つからない状況です。

% aws --version
aws-cli/2.15.16 Python/3.11.6 Darwin/22.6.0 exe/x86_64 prompt/off
% aws ivs list-playback-restriction-policies --profile shimizu.toshiya

usage: aws [options] <command> <subcommand> [<subcommand> ...] [parameters]
To see help text, you can run:

  aws help
  aws <command> help
  aws <command> <subcommand> help

aws: error: argument operation: Invalid choice, valid choices are:

batch-get-channel                        | batch-get-stream-key
batch-start-viewer-session-revocation    | create-channel
create-recording-configuration           | create-stream-key
delete-channel                           | delete-playback-key-pair
delete-recording-configuration           | delete-stream-key
get-channel                              | get-playback-key-pair
get-recording-configuration              | get-stream
get-stream-key                           | get-stream-session
import-playback-key-pair                 | list-channels
list-playback-key-pairs                  | list-recording-configurations
list-stream-keys                         | list-stream-sessions
list-streams                             | list-tags-for-resource
put-metadata                             | start-viewer-session-revocation
stop-stream                              | tag-resource
untag-resource                           | update-channel
help

確認してみたところ、AWS CLI v1ではバージョン1.32.33でPlayback Restriction Policyに対応済みのようです。

AWS CLI v2でもすぐに対応するとは思いつつも、AWS CLIでPlayback Restriction Policyを真っ先に操作してみたい!ということで、以下ブログエントリを参考に、CloudShellで使い捨てなAWS CLI v1環境を準備して動作を確認しました。

上記ブログエントリ当時のERROR/WARNING内容と少し異なるようですが、バージョン1.32.33のAWS CLIが実行できるようなのでこちらで検証を進めています。

[cloudshell-user@ip-10-130-54-157 ~]$ aws --version
aws-cli/2.15.15 Python/3.11.6 Linux/6.1.66-91.160.amzn2023.x86_64 exec-env/CloudShell exe/x86_64.amzn.2023 prompt/off
[cloudshell-user@ip-10-130-54-157 ~]$ sudo pip3 uninstall -y awsebcli && sudo pip3 install --upgrade awscli
WARNING: Skipping awsebcli as it is not installed.
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

<中略>

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
boto3 1.28.62 requires botocore<1.32.0,>=1.31.62, but you have botocore 1.34.33 which is incompatible.
boto3 1.28.62 requires s3transfer<0.8.0,>=0.7.0, but you have s3transfer 0.10.0 which is incompatible.
Successfully installed awscli-1.32.33 botocore-1.34.33 colorama-0.4.4 docutils-0.16 pyasn1-0.5.1 rsa-4.7.2 s3transfer-0.10.0
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
[cloudshell-user@ip-10-130-54-157 ~]$ aws --version
aws-cli/1.32.33 Python/3.9.16 Linux/6.1.66-91.160.amzn2023.x86_64 exec-env/CloudShell botocore/1.34.33

Playback Restriction Policyの表示(ListとGet)

AWS CLI環境の準備ができたら、まずは前回のブログエントリ執筆時に作成したPlayback Restriction Policyの表示からはじめてみます。

aws ivs list-playback-restriction-policiesコマンド、aws ivs get-playback-restriction-policyコマンドを使用します。

aws ivs list-playback-restriction-policiesコマンドはオプションなしで実行可能です。

$ aws ivs list-playback-restriction-policies

以下のような実行結果となります。

$ aws ivs list-playback-restriction-policies
{
    "playbackRestrictionPolicies": [
        {
            "allowedCountries": [
                "JP"
            ],
            "allowedOrigins": [
                "https://ivs.example.net"
            ],
            "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/grxxxxxxxxHT",
            "enableStrictOriginEnforcement": false,
            "name": "playback-restriction-policy-1",
            "tags": {}
        }
    ]
}

aws ivs get-playback-restriction-policyコマンドは--arnオプションでplayback restriction policyのARNを指定します。

$ aws ivs get-playback-restriction-policy \
    --arn <value>

実行結果は以下です。出力内容はaws ivs list-playback-restriction-policiesと同じですね。

$ aws ivs get-playback-restriction-policy --arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/grxxxxxxxxHT"
{
    "playbackRestrictionPolicy": {
        "allowedCountries": [
            "JP"
        ],
        "allowedOrigins": [
            "https://ivs.example.net"
        ],
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/grxxxxxxxxHT",
        "enableStrictOriginEnforcement": false,
        "name": "playback-restriction-policy-1",
        "tags": {}
    }
}

Playback Restriction Policyの作成(Create)

続いてPlayback Restriction Policyの作成です。aws ivs create-playback-restriction-policyコマンドを使用します。

オプションとしてPlayback Restriction Policy作成時に指定する項目、Policyの名前やAllowed Countries、Allowed Origins、そしてStrict origin enforcementの有無などを設定します。 ただし、いずれも指定が必須ではありません。

$ aws ivs create-playback-restriction-policy \
   [--name <value>] \
   [--allowed-countries <value>] \
   [--allowed-origins <value>] \
   [--enable-strict-origin-enforcement | --no-enable-strict-origin-enforcement]

--nameオプションは作成するPlayback restriction policyの名前ですね。名前なので必須と思いきや、これも必須ではありません。

--allowed-countriesで再生許可をする国を指定します。国の指定方法はISO 3166-1 alpha-2というコードを使用する必要があります。わかりやすいところでいえば、日本ならJP、アメリカ合衆国ならUSとなります。指定しなかった場合はすべての国に対して再生が許可されます。

--allowed-originsでは再生を許可する(CORSレスポンスヘッダを返す)サイトを指定します。指定方法はOriginヘッダの書式と同様で https://example1.com という形式のほか、ワイルドカードを使って https://*.example2.com という形式での指定もできます。指定をしない場合はすべてのOriginが許可対象となります。また 指定可能なOriginが5つまでである点に注意しましょう。(Service Quotas (Low-Latency Streaming) - Amazon Interactive Video Service

Strict origin enforcementの有効/無効は--enable-strict-origin-enforcementまたは--no-enable-strict-origin-enforcementで指定します。指定しない場合(デフォルト)は無効となります。

実行結果は以下のようになります。コマンドの返り値として作成したPlayback Restriction Policyの詳細が返ります。

$ aws ivs create-playback-restriction-policy \
>     --name prp-created-by-aws-cli \
>     --allowed-countries '["JP","US"]' \
>     --allowed-origins '["https://*.example.net","http://ivs.example.net"]' \
>     --enable-strict-origin-enforcement
{
    "playbackRestrictionPolicy": {
        "allowedCountries": [
            "JP",
            "US"
        ],
        "allowedOrigins": [
            "https://*.example.net",
            "http://ivs.example.net"
        ],
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8",
        "enableStrictOriginEnforcement": true,
        "name": "prp-created-by-aws-cli",
        "tags": {}
    }
}

実行後、aws ivs list-playback-restriction-policiesコマンドを実行してみました。2つ目のPlayback Restriction Policyが作成されていますね。

$ aws ivs list-playback-restriction-policies
{
    "playbackRestrictionPolicies": [
        {
            "allowedCountries": [
                "JP",
                "US"
            ],
            "allowedOrigins": [
                "https://*.example.net",
                "http://ivs.example.net"
            ],
            "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8",
            "enableStrictOriginEnforcement": true,
            "name": "prp-created-by-aws-cli",
            "tags": {}
        },
        {
            "allowedCountries": [
                "JP"
            ],
            "allowedOrigins": [
                "https://ivs.example.net"
            ],
            "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/grxxxxxxxxHT",
            "enableStrictOriginEnforcement": false,
            "name": "playback-restriction-policy-1",
            "tags": {}
        }
    ]
}

Playback Restriction Policyの更新(Update)

続いてPlayback Restriction Policyの更新を行います。更新はaws ivs update-playback-restriction-policyコマンドです。

更新(変更)対象となるPlayback restriction policyのARNが必須指定なオプションです。そのほか、変更後のPolicyの名前やAllowed Countries、Allowed Origins、そしてStrict origin enforcementの有無などをオプションで設定します。

$ aws ivs update-playback-restriction-policy \
    --arn <value> \
   [--name <value>] \
   [--allowed-countries <value>] \
   [--allowed-origins <value>] \
   [--enable-strict-origin-enforcement | --no-enable-strict-origin-enforcement]

実際にaws ivs update-playback-restriction-policyコマンドの実行を確認してみます。まずはPlayback Restriction Policyの変更前の状態をaws ivs get-playback-restriction-policyコマンドで確認します。

$ aws ivs get-playback-restriction-policy \
>    --arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8"
{
    "playbackRestrictionPolicy": {
        "allowedCountries": [
            "JP",
            "US"
        ],
        "allowedOrigins": [
            "https://*.example.net",
            "http://ivs.example.net"
        ],
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8",
        "enableStrictOriginEnforcement": true,
        "name": "prp-created-by-aws-cli",
        "tags": {}
    }
}

日本国内からのみ再生を許可するように、そして再生を許可するサイト(Origin)も変更してみます。

$ aws ivs update-playback-restriction-policy \
>     --arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8" \
>     --allowed-countries '["JP"]' \
>     --allowed-origins '["https://ivs.example.net"]'
{
    "playbackRestrictionPolicy": {
        "allowedCountries": [
            "JP"
        ],
        "allowedOrigins": [
            "https://ivs.example.net"
        ],
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8",
        "enableStrictOriginEnforcement": true,
        "name": "prp-created-by-aws-cli",
        "tags": {}
    }
}

返り値から変更できていることが確認できますね。念のため、aws ivs get-playback-restriction-policyコマンドでも確認してみます。

$ aws ivs get-playback-restriction-policy \
>     --arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8"{
    "playbackRestrictionPolicy": {
        "allowedCountries": [
            "JP"
        ],
        "allowedOrigins": [
            "https://ivs.example.net"
        ],
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8",
        "enableStrictOriginEnforcement": true,
        "name": "prp-created-by-aws-cli",
        "tags": {}
    }
}

さらに、Strict origin enforcementを無効にしてみます。

$ aws ivs update-playback-restriction-policy \
>     --arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8" \
>     --no-enable-strict-origin-enforcement
{
    "playbackRestrictionPolicy": {
        "allowedCountries": [
            "JP"
        ],
        "allowedOrigins": [
            "https://ivs.example.net"
        ],
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8",
        "enableStrictOriginEnforcement": false,
        "name": "prp-created-by-aws-cli",
        "tags": {}
    }
}
$ aws ivs get-playback-restriction-policy \
> --arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8"
{
    "playbackRestrictionPolicy": {
        "allowedCountries": [
            "JP"
        ],
        "allowedOrigins": [
            "https://ivs.example.net"
        ],
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8",
        "enableStrictOriginEnforcement": false,
        "name": "prp-created-by-aws-cli",
        "tags": {}
    }
}

Playback Restriction Policyの削除(Delete)

Playback Restriction Policyの削除はaws ivs delete-playback-restriction-policyコマンドで行います。--arnオプションで削除対象のPlayback Restriction PolicyのARNを指定します。

$ aws ivs delete-playback-restriction-policy \
    --arn <value>

以下が実行結果です。実行後の返り値はありませんので、実行前後でaws ivs list-playback-restriction-policiesコマンドで確認しています。

$ aws ivs list-playback-restriction-policies
{
    "playbackRestrictionPolicies": [
        {
            "allowedCountries": [
                "JP"
            ],
            "allowedOrigins": [
                "https://ivs.example.net"
            ],
            "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8",
            "enableStrictOriginEnforcement": false,
            "name": "prp-created-by-aws-cli",
            "tags": {}
        },
        {
            "allowedCountries": [
                "JP"
            ],
            "allowedOrigins": [
                "https://ivs.example.net"
            ],
            "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/grxxxxxxxxHT",
            "enableStrictOriginEnforcement": false,
            "name": "playback-restriction-policy-1",
            "tags": {}
        }
    ]
}
$ aws ivs delete-playback-restriction-policy \
>     --arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/5Fxxxxxxxxm8"
$ aws ivs list-playback-restriction-policies
{
    "playbackRestrictionPolicies": [
        {
            "allowedCountries": [
                "JP"
            ],
            "allowedOrigins": [
                "https://ivs.example.net"
            ],
            "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/grxxxxxxxxHT",
            "enableStrictOriginEnforcement": false,
            "name": "playback-restriction-policy-1",
            "tags": {}
        }
    ]
}

Channelの作成や更新時にPlayback Restriction PolicyをAWS CLIでアタッチする

Playback Restriction Policyの表示、作成、更新、削除をAWS CLIで行う方法についてそれぞれ確認してきました。最後に、IVS Low-Latency StreamingのChannelリソースに対して、Playback Restriction PolicyをChannel作成時にアタッチする方法、またChannel更新時にアタッチする方法について確認してみます。

Channel作成時のaws ivs create-channelコマンド、もしくはChannel更新時のaws ivs update-channelコマンドそれぞれの実行時に--playback-restriction-policy-arnオプションでアタッチするPlayback Restriction Policyを指定することができます。Playback Restriction PolicyはARNでの指定になる点に注意しましょう。

なおChannelの作成、更新などは以下エントリなどを参照ください。

あらかじめアタッチ用のPlayback Restriction Policyをaws ivs create-playback-restriction-policyコマンドで作成しておきます。

$ aws ivs create-playback-restriction-policy \
>     --name prp-created-by-aws-cli \
>     --allowed-countries '["JP","US"]' \
>     --allowed-origins '["https://*.example.net","http://ivs.example.net"]' \
>     --no-enable-strict-origin-enforcement
{
    "playbackRestrictionPolicy": {
        "allowedCountries": [
            "JP",
            "US"
        ],
        "allowedOrigins": [
            "https://*.example.net",
            "http://ivs.example.net"
        ],
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/U7xxxxxxxxIY",
        "enableStrictOriginEnforcement": false,
        "name": "prp-created-by-aws-cli",
        "tags": {}
    }
}

Channelの新規作成(create-channel)の場合

まずはChannelリソースの新規作成時です。aws ivs create-channelコマンドにオプション--playback-restriction-policy-arnでPlayback Restriction PolicyのARNを指定します。

$ aws ivs create-channel \
>     --name "prp-aws-cli-test-channel-1" \
>     --playback-restriction-policy-arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/U7xxxxxxxxIY"
{
    "channel": {
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/SZxxxxxxxxxb",
        "authorized": false,
        "ingestEndpoint": "62xxxxxxxx2b.global-contribute.live-video.net",
        "insecureIngest": false,
        "latencyMode": "LOW",
        "name": "prp-aws-cli-test-channel-1",
        "playbackRestrictionPolicyArn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/U7xxxxxxxxIY",
        "playbackUrl": "https://62xxxxxxxx2b.ap-northeast-1.playback.live-video.net/api/video/v1/ap-northeast-1.123456789012.channel.SZxxxxxxxxxb.m3u8",
        "preset": "",
        "recordingConfigurationArn": "",
        "tags": {},
        "type": "STANDARD"
    },
    "streamKey": {
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:stream-key/LgxxxxxxxxU2",
        "channelArn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/SZxxxxxxxxxb",
        "tags": {},
        "value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
}

Channelの更新(update-channel)の場合

更新についても同様に、aws ivs update-channelコマンドにオプション--playback-restriction-policy-arnでPlayback Restriction PolicyのARNを指定します。

まずはPlayback Restriction PolicyがアタッチされていないChannelをaws ivs create-channelコマンドで作成します。

$ aws ivs create-channel \
>     --name "prp-aws-cli-test-channel-2"
{
    "channel": {
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/AlxxxxxxxxFy",
        "authorized": false,
        "ingestEndpoint": "62xxxxxxxx2b.global-contribute.live-video.net",
        "insecureIngest": false,
        "latencyMode": "LOW",
        "name": "prp-aws-cli-test-channel-2",
        "playbackRestrictionPolicyArn": "",
        "playbackUrl": "https://62xxxxxxxx2b.ap-northeast-1.playback.live-video.net/api/video/v1/ap-northeast-1.123456789012.channel.AlxxxxxxxxFy.m3u8",
        "preset": "",
        "recordingConfigurationArn": "",
        "tags": {},
        "type": "STANDARD"
    },
    "streamKey": {
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:stream-key/e9xxxxxxxxWZ",
        "channelArn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/AlxxxxxxxxFy",
        "tags": {},
        "value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
}

aws ivs update-channelコマンドでChannelリソースの更新を行います。実行後、"playbackRestrictionPolicyArn"に値が設定されていることが確認できますね。

$ aws ivs update-channel \
>     --arn "arn:aws:ivs:ap-northeast-1:123456789012:channel/AlxxxxxxxxFy" \
>     --playback-restriction-policy-arn "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/U7xxxxxxxxIY"
{
    "channel": {
        "arn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/AlxxxxxxxxFy",
        "authorized": false,
        "ingestEndpoint": "62xxxxxxxx2b.global-contribute.live-video.net",
        "insecureIngest": false,
        "latencyMode": "LOW",
        "name": "prp-aws-cli-test-channel-2",
        "playbackRestrictionPolicyArn": "arn:aws:ivs:ap-northeast-1:123456789012:playback-restriction-policy/U7xxxxxxxxIY",
        "playbackUrl": "https://62xxxxxxxx2b.ap-northeast-1.playback.live-video.net/api/video/v1/ap-northeast-1.123456789012.channel.AlxxxxxxxxFy.m3u8",
        "preset": "",
        "recordingConfigurationArn": "",
        "tags": {},
        "type": "STANDARD"
    }
}

まとめ

AWS CLIを使ってIVS Low-Latency StreamingのPlayback Restriction Policyを操作してみました。List/GetとCreate、Update、そしてDeleteと、シンプルに操作体系がまとまっている印象です。Allowed Countries指定時の国コード、Allowed Origins指定時の書式、Strict origin enforcementの有効/無効の指定方法などがポイントになるかと思います。しっかり抑えておきましょう。また本エントリ執筆時点で未対応だったAWS CLI v2、きっとすぐに対応されると思います、待ち遠しいですね。