1.16. バケット通知

ストレージ管理者は、これらの API を使用してバケット通知メカニズムの設定および制御インターフェイスを提供できます。API トピックは、特定のエンドポイントの定義が含まれる名前が付けられたオブジェクトです。バケット通知では、トピックを特定のバケットに関連付けます。S3 バケット操作 セクションでは、バケット通知の詳細が表示されます。

注記

すべてのトピックアクションでは、パラメーターは URL エンコードされ、application/x-www-form-urlencoded コンテンツタイプを使用してメッセージのボディーで送信されます。

注記

トピックの更新を有効にするには、トピックにすでに関連付けられているバケット通知を再作成する必要があります。

1.16.1. 前提条件

  • Ceph Object Gateway 上にバケット通知を作成します。

1.16.2. トピックの作成

バケット通知を作成する前に、トピックを作成できます。トピックは Simple Notification Service (SNS) エンティティーで、すべてのトピック操作 (つまり createdeletelist、および get) は SNS 操作です。トピックには、バケット通知の作成時に使用されるエンドポイントパラメーターが必要です。リクエストが正常に行われると、レスポンスには、バケット通知要求でこのトピックを参照するために後で使用できるトピックの Amazon Resource Name (ARN) が含まれます。

注記

topic_arn はバケット通知設定を提供し、トピックの作成後に生成されます。

前提条件

  • 稼働中の Red Hat Ceph Storage クラスターがある。
  • ルートレベルのアクセス。
  • Ceph Object Gateway のインストール
  • ユーザーアクセスキーおよびシークレットキー。
  • エンドポイントパラメーター。

手順

  1. 以下の要求形式でトピックを作成します。

    構文

    POST
    Action=CreateTopic
    &Name=TOPIC_NAME
    [&Attributes.entry.1.key=amqp-exchange&Attributes.entry.1.value=EXCHANGE]
    [&Attributes.entry.2.key=amqp-ack-level&Attributes.entry.2.value=none|broker|routable]
    [&Attributes.entry.3.key=verify-ssl&Attributes.entry.3.value=true|false]
    [&Attributes.entry.4.key=kafka-ack-level&Attributes.entry.4.value=none|broker]
    [&Attributes.entry.5.key=use-ssl&Attributes.entry.5.value=true|false]
    [&Attributes.entry.6.key=ca-location&Attributes.entry.6.value=FILE_PATH]
    [&Attributes.entry.7.key=OpaqueData&Attributes.entry.7.value=OPAQUE_DATA]
    [&Attributes.entry.8.key=push-endpoint&Attributes.entry.8.value=ENDPOINT]

    リクエストパラメーターを以下に示します。

    • Endpoint: 通知を送信するエンドポイントの URL。
    • OpaqueData: 不透明なデータはトピック設定で設定され、トピックによって発生するすべての通知に追加されます。
    • HTTP エンドポイント:

      • URL: http[s]://FQDN[: PORT ]
      • ポートのデフォルト: HTTP または HTTPS にそれぞれ 80 または 443 を使用します。
      • verify-ssl: サーバー証明書がクライアントによって検証されているかどうかを示します。デフォルトでは true です。
    • AMQP0.9.1 エンドポイント:

      • URL: amqp://[USER : PASSWORD @] FQDN [: PORT][/VHOST].
      • ユーザーおよびグループのデフォルト値はそれぞれ guestguest です。
      • ユーザーおよびパスワードは、HTTPS でのみ提供できます。そうしないと、トピック作成要求は拒否されます。
      • Port のデフォルト値 は 5672 です。
      • vhost のデフォルトは/です。
      • amqp-exchange: 交換は存在し、トピックに基づいてメッセージをルーティングできる必要があります。これは AMQP0.9.1 の必須パラメーターです。同じエンドポイントを参照するさまざまなトピックが同じ交換を使用する必要があります。
      • amqp-ack-level: 最終宛先に送信される前にメッセージがブローカーで永続化される可能性があるため、終了確認は不要です。確認方法は 3 つあります。

        • none: ブローカーに送信された場合にメッセージが 配信されている と見なされます。
        • broker: デフォルトでは、メッセージはブローカーによって確認応答されると 配信されている と見なされます。
        • routable: ブローカーがコンシューマーにルーティングできる場合、メッセージは 配信されている と見なされます。

          注記

          特定のパラメーターのキーと値は、同じ行または特定の順序で存在する必要はありませんが、同じインデックスを使用する必要があります。属性インデックスは、特定の値から順番にしたり、開始したりする必要はありません。

          注記

          topic-name は AMQP トピックに使用されます。

    • Kafka エンドポイント:

      • URL: kafka://[USER: PASSWORD @] FQDN[: PORT].
      • use-ssl がデフォルトで false に設定される場合。use-ssltrue に設定されている場合は、ブローカーへの接続にセキュアな接続が使用されます。
      • ca-location が指定され、セキュアな接続が使用される場合は、ブローカーを認証するために、デフォルトの CA ではなく、指定された CA が使用されます。
      • ユーザーおよびパスワードは HTTP[S] でのみ提供できます。そうでない場合、トピック作成リクエストは拒否されます。
      • ユーザーおよびパスワードは use-ssl とのみ提供でき、ブローカーへの接続に失敗していました。
      • Port のデフォルト値 は 9092 です。
      • kafka-ack-level: 最終宛先に送信される前にメッセージがブローカーで永続化される可能性があるため、終了確認は不要です。確認方法は 2 つあります。

        • none: ブローカーに送信された場合にメッセージが 配信されている と見なされます。
        • broker: デフォルトでは、メッセージはブローカーによって確認応答されると 配信されている と見なされます。
  2. 次の形式でレスポンスを作成します。

    構文

    <CreateTopicResponse xmlns="https://sns.amazonaws.com/doc/2010-03-31/">
        <CreateTopicResult>
            <TopicArn></TopicArn>
        </CreateTopicResult>
        <ResponseMetadata>
            <RequestId></RequestId>
        </ResponseMetadata>
    </CreateTopicResponse>

    注記

    レスポンスのトピックの Amazon Resource Name (ARN) の形式は、arn:aws:sns:ZONE_GROUP:TENANT:TOPIC になります。

    以下は AMQP0.9.1 エンドポイントの例になります。

    構文

    "client.create_topic(Name='my-topic' , Attributes={'push-endpoint': 'amqp://127.0.0.1:5672', 'amqp-exchange': 'ex1', 'amqp-ack-level': 'broker'})"

1.16.3. トピック情報の取得

特定のトピックに関する情報を返します。これには、指定されている場合にはエンドポイント情報を含めることができます。

前提条件

  • 稼働中の Red Hat Ceph Storage クラスターがある。
  • ルートレベルのアクセス。
  • Ceph Object Gateway のインストール
  • ユーザーアクセスキーおよびシークレットキー。
  • エンドポイントパラメーター。

手順

  1. 以下の要求形式でトピック情報を取得します。

    構文

    POST
    Action=GetTopic
    &TopicArn=TOPIC_ARN

    レスポンスフォーマットの例を以下に示します。

    <GetTopicResponse>
      <GetTopicRersult>
        <Topic>
          <User>
          </User>
          <Name>
          </Name>
          <EndPoint>
            <EndpointAddress>
            </EndpointAddress>
            <EndpointArgs>
            </EndpointArgs>
            <EndpointTopic>
            </EndpointTopic>
          </EndPoint>
          <TopicArn>
          </TopicArn>
          <OpaqueData>
          </OpaqueData>
        </Topic>
      </GetTopicResult>
      <ResponseMetadata>
        <RequestId>
        </RequestId>
      </ResponseMetadata>
    </GetTopicResponse>

    タグおよびその定義を以下に示します。

    • User: トピックを作成したユーザーの名前。
    • Name: トピックの名前。
    • EndpointAddress: エンドポイントの URL。エンドポイント URL にユーザーおよびパスワード情報が含まれる場合、リクエストは HTTPS 経由で行う必要があります。そうでない場合、トピックの取得要求は拒否されます。
    • EndPointArgs: エンドポイント引数。
    • EndpointTopic: エンドポイントに送信されるトピック名は、上記のトピック名とは異なる場合があります。
    • TopicArn: Topic ARN。

1.16.4. トピックの一覧表示

ユーザーが定義したトピックを一覧表示します。

前提条件

  • 稼働中の Red Hat Ceph Storage クラスターがある。
  • ルートレベルのアクセス。
  • Ceph Object Gateway のインストール
  • ユーザーアクセスキーおよびシークレットキー。
  • エンドポイントパラメーター。

手順

  1. 以下の要求形式でトピック情報を一覧表示します。

    POST
    Action=ListTopics

    レスポンスフォーマットの例を以下に示します。

    <ListTopicdResponse xmlns="https://sns.amazonaws.com/doc/2020-03-31/">
      <ListTopicsRersult>
        <Topics>
          <member>
            <User>
            </User>
            <Name>
            </Name>
            <EndPoint>
              <EndpointAddress>
              </EndpointAddress>
              <EndpointArgs>
              </EndpointArgs>
              <EndpointTopic>
              </EndpointTopic>
            </EndPoint>
            <TopicArn>
            </TopicArn>
            <OpaqueData>
            </OpaqueData>
          </member>
        </Topics>
      </ListTopicsResult>
      <ResponseMetadata>
        <RequestId>
        </RequestId>
      </ResponseMetadata>
    </ListTopicsResponse>
    注記

    エンドポイント URL にユーザーおよびパスワード情報が含まれる場合は、トピックのいずれかで要求を行う必要があります。そうでない場合、トピック一覧の要求は拒否されます。

1.16.5. トピックの削除

削除したトピックを削除すると、操作はなく、失敗は発生しません。

前提条件

  • 稼働中の Red Hat Ceph Storage クラスターがある。
  • ルートレベルのアクセス。
  • Ceph Object Gateway のインストール
  • ユーザーアクセスキーおよびシークレットキー。
  • エンドポイントパラメーター。

手順

  1. 以下の要求形式でトピックを削除します。

    構文

    POST
    Action=DeleteTopic
    &TopicArn=TOPIC_ARN

    レスポンスフォーマットの例を以下に示します。

    <DeleteTopicResponse xmlns="https://sns.amazonaws.com/doc/2020-03-31/">
      <ResponseMetadata>
        <RequestId>
        </RequestId>
      </ResponseMetadata>
    </DeleteTopicResponse>

1.16.6. イベントレコード

イベントは、Ceph Object Gateway によって行われる操作に関する情報を保持し、選択したエンドポイント (HTTP、HTTPS、Kafka、または AMQ0.9.1 など) 上のペイロードとして送信されます。イベントレコードは JSON 形式になります。

{"Records":[
    {
        "eventVersion":"2.1",
        "eventSource":"ceph:s3",
        "awsRegion":"us-east-1",
        "eventTime":"2019-11-22T13:47:35.124724Z",
        "eventName":"s3:ObjectCreated:Put",
        "userIdentity":{
            "principalId":"tester"
        },
        "requestParameters":{
            "sourceIPAddress":""
        },
        "responseElements":{
            "x-amz-request-id":"503a4c37-85eb-47cd-8681-2817e80b4281.5330.903595",
            "x-amz-id-2":"14d2-zone1-zonegroup1"
        },
        "s3":{
            "s3SchemaVersion":"1.0",
            "configurationId":"mynotif1",
            "bucket":{
                "name":"mybucket1",
                "ownerIdentity":{
                    "principalId":"tester"
                },
                "arn":"arn:aws:s3:us-east-1::mybucket1",
                "id":"503a4c37-85eb-47cd-8681-2817e80b4281.5332.38"
            },
            "object":{
                "key":"myimage1.jpg",
                "size":"1024",
                "eTag":"37b51d194a7513e45b56f6524f2d51f2",
                "versionId":"",
                "sequencer": "F7E6D75DC742D108",
                "metadata":[],
                "tags":[]
            }
        },
        "eventId":"",
        "opaqueData":"me@example.com"
    }
]}

以下はイベントレコードのキーおよびその定義です。

  • awsRegion: Zonegroup。
  • eventTime: イベントがトリガーされたタイミングを示すタイムスタンプ。
  • eventName: イベントのタイプ。
  • userIdentity.principalId: イベントを開始したユーザーの ID。
  • requestParameters.sourceIPAddress: イベントをトリガーしたクライアントの IP アドレス。このフィールドはサポートされません。
  • responseElements.x-amz-request-id: イベントをトリガーしたリクエスト ID。
  • responseElements.x_amz_id_2: イベントがトリガーされた Ceph Object Gateway の IP アドレスID 形式は RGWID-ZONE-ZONEGROUP です。
  • s3.configurationId: イベントを作成した通知 ID。
  • s3.bucket.name: バケットの名前。
  • s3.bucket.ownerIdentity.principalId: バケットの所有者。
  • s3.bucket.arn: バケットの Amazon Resource Name(ARN)。
  • s3.bucket.id: バケットのアイデンティティー。
  • s3.object.key: オブジェクトキー。
  • s3.object.size: オブジェクトのサイズ
  • s3.object.eTag: オブジェクト etag。
  • s3.object.version: バージョン化されたバケットのオブジェクトバージョン。
  • s3.object.sequencer: 16 進数形式でオブジェクトごとの変更識別子を増加させます。
  • s3.object.metadata: x-amz-meta として送信されるオブジェクトにメタデータセット。
  • s3.object.tags: オブジェクトに設定されたタグ。
  • s3.eventId: イベントの一意のアイデンティティー
  • s3.opaqueData: Opaque データはトピック設定で設定され、トピックによってトリガーされるすべての通知に追加されます。

関連情報

1.16.7. サポートされるイベントタイプ

以下のイベントタイプがサポートされます。

  • s3:ObjectCreated:*
  • s3:ObjectCreated:Put
  • s3:ObjectCreated:Post
  • s3:ObjectCreated:Copy
  • s3:ObjectCreated:CompleteMultipartUpload
  • s3:ObjectRemoved:*
  • s3:ObjectRemoved:Delete
  • s3:ObjectRemoved:DeleteMarkerCreated

1.16.8. 関連情報

  • 詳細は、Red Hat Ceph Storage Object Gateway 設定および管理ガイドバケット通知の作成 セクションを参照してください。