[JAWS-UG CLI] SNS:#2 通知先の登録 (e-mail)

AWS CLIを利用して、SNSのトピックに通知先を登録してみます。



前提条件
========


SNSへの権限
-----------

SNSに対してフル権限があること。


AWS CLIのバージョン
-------------------

以下のバージョンで動作確認済

- AWS CLI 1.11.76

```bash:コマンド:
aws --version
```

結果(例):

      aws-cli/1.11.70 Python/2.7.12 Linux/4.4.11-23.53.amzn1.x86_64 botocore/1.5.33

バージョンが古い場合は最新版に更新しましょう。

```bash:コマンド:
sudo -H pip install -U awscli
```


0. 準備
=======

まず変数の確認をします。

```bash:変数の確認:
cat << ETX

        AWS_DEFAULT_PROFILE: (0.1) ${AWS_DEFAULT_PROFILE}
        AWS_DEFAULT_REGION:  (0.2) ${AWS_DEFAULT_REGION}
        SNS_TOPIC_ARN        (0.3) ${SNS_TOPIC_ARN}

ETX
```

結果(例):

      AWS_DEFAULT_PROFILE: (0.1) <SNSにフル権限のあるプロファイル>
      AWS_DEFAULT_REGION:  (0.2) ap-northeast-1
      SNS_TOPIC_ARN        (0.3) arn:aws:sns:ap-northeast-1:XXXXXXXXXXXX:handson-20170417

変数が入っていない、適切でない場合は、それぞれの手順番号について作業を
行います。


0.1. プロファイルの指定
-----------------------

プロファイルの一覧を確認します。

```bash:コマンド:
cat ~/.aws/credentials \
       | grep '\[' \
       | sed 's/\[//g' | sed 's/\]//g'
```

結果(例):

      iamFull-prjz-mbpr13
      <SNSにフル権限のあるプロファイル>

```bash:変数の設定:
export AWS_DEFAULT_PROFILE='<SNSにフル権限のあるプロファイル>'
```


0.2. リージョンの指定
---------------------

```bash:変数の設定:
export AWS_DEFAULT_REGION='ap-northeast-1'
```


0.3. トピック名の指定
---------------------

購読するトピックを指定します。

```bash:変数の設定:
SNS_TOPIC_NAME='handson-20170417'
```

SNSでトピックを操作するときは、対象トピックのARNを特定する必要がありま
す。

```bash:変数の設定:
SNS_TOPIC_ARN=$( \
        aws sns list-topics \
          --query "Topics[?contains(TopicArn, \`${SNS_TOPIC_NAME}\`)].TopicArn" \
          --output text \
) \
        && echo ${SNS_TOPIC_ARN}
```

結果(例):

      arn:aws:sns:ap-northeast-1:XXXXXXXXXXXX:handson-20170417


再確認
------

```bash:変数の確認:
cat << ETX

        AWS_DEFAULT_PROFILE: (0.1) ${AWS_DEFAULT_PROFILE}
        AWS_DEFAULT_REGION:  (0.2) ${AWS_DEFAULT_REGION}
        SNS_TOPIC_ARN        (0.3) ${SNS_TOPIC_ARN}

ETX
```

結果(例):

      AWS_DEFAULT_PROFILE: (0.1) <SNSにフル権限のあるプロファイル>
      AWS_DEFAULT_REGION:  (0.2) ap-northeast-1
      SNS_TOPIC_ARN        (0.3) arn:aws:sns:ap-northeast-1:XXXXXXXXXXXX:handson-20170417


1. 事前作業
===========


1.1. 通知先(エンドポイント)の決定
---------------------------------

通知先となるエンドポイントとプロトコルを決定します。

今回は、プロトコルとしてEmailを利用して通知するので、メールアドレスが
エンドポイントとなります。

```bash:変数の設定:
SNS_NOTIF_ENDPOINT='<通知先として登録するメールアドレス>'
```

```bash:変数の設定:
SNS_NOTIF_PROTOCOL='email'
```


1.2. Subscriptionの確認
-----------------------

登録予定の通知先がトピックに登録されていないことを確認しましょう。

```bash:コマンド:
aws sns list-subscriptions-by-topic \
        --topic-arn ${SNS_TOPIC_ARN} \
        --query "Subscriptions[?Endpoint == \`${SNS_NOTIF_ENDPOINT}\`]"
```

結果(例):

      []


1.3. 購読者数の確認
-------------------

Confirmationの実施前に、トピックの購読者がどれくらいいるか確認してみま
しょう。

```bash:変数の設定:
SNS_COUNT_CONFIRMD=$( \
        aws sns get-topic-attributes \
          --topic-arn ${SNS_TOPIC_ARN} \
          --query "Attributes.SubscriptionsConfirmed" \
          --output text \
) \
        && echo ${SNS_COUNT_CONFIRMD}
```

結果(例):

      0

トピックを作成した直後であれば0のはずです。


2. トピックの購読
=================


2.1. サブスクライブの実施
-------------------------

トピックの購読を行います。

```bash:変数の確認:
cat << ETX

        SNS_TOPIC_ARN:      ${SNS_TOPIC_ARN}
        SNS_NOTIF_PROTOCOL: ${SNS_NOTIF_PROTOCOL}
        SNS_NOTIF_ENDPOINT: ${SNS_NOTIF_ENDPOINT}

ETX
```

```bash:コマンド:
aws sns subscribe \
        --topic-arn ${SNS_TOPIC_ARN} \
        --protocol ${SNS_NOTIF_PROTOCOL} \
        --notification-endpoint ${SNS_NOTIF_ENDPOINT}
```

結果(例):

      {
        "SubscriptionArn": "pending confirmation"
      }


2.2. Subscriptionの状況確認
---------------------------

Subscriptionの状況を確認してみましょう。

```bash:変数の設定:
SNS_SUBSCRIPTION_ARN=$( \
        aws sns list-subscriptions-by-topic \
          --topic-arn ${SNS_TOPIC_ARN} \
          --query "Subscriptions[?Endpoint == \`${SNS_NOTIF_ENDPOINT}\`].SubscriptionArn" \
          --output text \
) \
        && echo ${SNS_SUBSCRIPTION_ARN}
```


結果(例):

      PendingConfirmation

Comfirmation前なので、SubscriptionArnの値が"pendingConfirmation"となっ
ているはずです。


2.3. Subscription Confirmationの受信
------------------------------------

登録したメールアドレス宛に "Subscription Confirmation"という表題のメー
ルが届いているはずです。 (SNSでは、エンドポイントへのConfirmation通知
以外でTokenを取得することはできません。)

Subscribeの承認に必要なTokenが、この通知に含まれています。

emailの場合、通知されてきたHTMLメールの'Confirm subscription'のリンク
先のURLにToken文字列が含まれています。

URL(例):

      https://sns.ap-northeast-1.amazonaws.com/confirmation.html?TopicArn=arn:aws:sns:ap-northeast-1:XXXXXXXXXXXX:handson-20170417&Token=2336412f37fb687f5d51e6e241d638b114f4ea40797156d59440ce34e67a7253af4c0641c81e3c4984b032ada9b7fc14668a462c383e2fb12b21a42a974b9fd47646f03f3158413a00692d5ef277785a8b4dde345639236f8365dbf35df89e8bdd512c965c8da54adbb071a667528d5a&Endpoint=<通知先として登録するメールアドレス>

このURLをコピーして、変数に格納しましょう。 URLに&が含まれているので、
値をシングルクォートで囲む必要があります。

```bash:変数の設定:
SNS_CONFIRM_URL='<Confirm subscriptionのリンク先URL>'
```

URLからTokenを取り出して変数に定義します。

```bash:変数の設定:
SNS_CONFIRM_TOKEN=$( \
        echo ${SNS_CONFIRM_URL} |\
        sed 's/^.*&Token=//' |\
        sed 's/&Endpoint.*$//' \
) \
        && echo ${SNS_CONFIRM_TOKEN}
```

Token(例):

      2336412f37fb687f5d51e6e241d638b114f4ea40797156d59440ce34e67a7253af4c0641c81e3c4984b032ada9b7fc14668a462c383e2fb12b21a42a974b9fd47646f03f3158413a00692d5ef277785a8b4dde345639236f8365dbf35df89e8bdd512c965c8da54adbb071a667528d5a


2.4. Confirmationの実施
-----------------------

購読の承認を行います。

Tokenの値を知っている人のみがConfirmationを行うことができます。

ここでは、購読者自身がUnsubscribeできないようにするために、
authenticate-on-unsubscribeオプションをtrueにします。

```bash:変数の確認:
cat << ETX

        SNS_TOPIC_ARN:     ${SNS_TOPIC_ARN}
        SNS_CONFIRM_TOKEN: ${SNS_CONFIRM_TOKEN}

ETX
```

```bash:コマンド:
aws sns confirm-subscription \
        --topic-arn ${SNS_TOPIC_ARN} \
        --token ${SNS_CONFIRM_TOKEN} \
        --authenticate-on-unsubscribe true
```

結果(例):

      {
        "SubscriptionArn": "arn:aws:sns:ap-northeast-1:XXXXXXXXXXXX:handson-20170417:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }


3. 事後作業
===========


3.1. Subscriptionの状況確認
---------------------------

Subscriptionの状況を確認してみましょう。

```bash:変数の設定:
SNS_SUBSCRIPTION_ARN=$( \
        aws sns list-subscriptions-by-topic \
          --topic-arn ${SNS_TOPIC_ARN} \
          --query "Subscriptions[?Endpoint == \`${SNS_NOTIF_ENDPOINT}\`].SubscriptionArn" \
          --output text \
) \
        && echo ${SNS_SUBSCRIPTION_ARN}
```


結果(例):

      arn:aws:sns:ap-northeast-1:XXXXXXXXXXXX:handson-20170417:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

SubscriptionArnの値が、'pendingConfirmation'からARNに変わっているはず
です。

SNSでは、endpointに関する操作をするときに、このSubscription ARNが必要
になります。


3.2. Subscription属性の確認
---------------------------

Subscriptionの属性を確認してみましょう。

```bash:コマンド:
aws sns get-subscription-attributes \
        --subscription-arn ${SNS_SUBSCRIPTION_ARN}
```

結果(例):

      {
        "Attributes": {
          "Endpoint": "<通知先として登録するメールアドレス>",
          "Protocol": "email",
          "RawMessageDelivery": "false",
          "ConfirmationWasAuthenticated": "true",
          "Owner": "XXXXXXXXXXXX",
          "SubscriptionArn": "arn:aws:sns:ap-northeast-1:XXXXXXXXXXXX:handson-20170417:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "TopicArn": "arn:aws:sns:ap-northeast-1:XXXXXXXXXXXX:handson-20170417"
        }
      }


3.3. 購読者数の確認
-------------------

Confirmationが完了すると自分が購読者となっているので、Confirmation前の
購読者数よりも増えているはずです。

```bash:変数の設定:
SNS_COUNT_CONFIRMD=$( \
        aws sns get-topic-attributes \
          --topic-arn ${SNS_TOPIC_ARN} \
          --query "Attributes.SubscriptionsConfirmed" \
          --output text \
) \
        && echo ${SNS_COUNT_CONFIRMD}
```

結果(例):

      1

自分しか購読者がいなければ1になっているはずです。

(topic-attributesに反映されるまでにタイムラグがあるようです。)


完了
====