From: Zac Dover Date: Wed, 19 Oct 2022 18:35:14 +0000 (+1000) Subject: doc/radosgw: refine "bucket notifications" X-Git-Tag: v16.2.11~232^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F48562%2Fhead;p=ceph.git doc/radosgw: refine "bucket notifications" This commit refines the English in the "Bucket Notifications REST API" section of the notifications.rst page (the "Bucket Notifications" page). Co-author: Cole Mitchell Signed-off-by: Zac Dover (cherry picked from commit a69dd10ddbbf952cc208f35c0ea04d644b582794) --- diff --git a/doc/radosgw/notifications.rst b/doc/radosgw/notifications.rst index 6b8e1cb05188..962f3e7c5ce8 100644 --- a/doc/radosgw/notifications.rst +++ b/doc/radosgw/notifications.rst @@ -120,7 +120,8 @@ Topics .. note:: In all topic actions, the parameters are URL-encoded and sent in the - message body using the ``application/x-www-form-urlencoded`` content type. + message body using this content type: + ``application/x-www-form-urlencoded``. Create a Topic @@ -131,11 +132,11 @@ which will be used later when a notification is created. A response is generated. A successful response includes the the topic's `ARN `_ (the "Amazon Resource Name", a unique identifier used to reference the topic). -To update a topic, use the same command that you used to create it (but use the -name of an existing topic and different endpoint values). +To update a topic, use the same command that you used to create it (but when +updating, use the name of an existing topic and different endpoint values). .. tip:: Any notification already associated with the topic must be re-created - for the topic update to take effect. + in order for the topic to update. .. note:: For rabbitmq, ``push-endpoint`` (with a hyphen in the middle) must be changed to ``push_endpoint`` (with an underscore in the middle). @@ -158,54 +159,83 @@ name of an existing topic and different endpoint values). Request parameters: -- push-endpoint: URI of an endpoint to send push notification to -- OpaqueData: opaque data is set in the topic configuration and added to all notifications triggered by the topic -- persistent: indication whether notifications to this endpoint are persistent (=asynchronous) or not ("false" by default) +- push-endpoint: This is the URI of an endpoint to send push notifications to. +- OpaqueData: Opaque data is set in the topic configuration and added to all + notifications that are triggered by the topic. +- persistent: This indicates whether notifications to this endpoint are + persistent (=asynchronous) or not persistent. (This is "false" by default.) - HTTP endpoint - URI: ``http[s]://[::@][:][/]`` - - user/password defaults to: guest/guest - - user/password may only be provided over HTTPS. If not, topic creation request will be rejected. - - port defaults to: 5672/5671 for unencrypted/SSL-encrypted connections - - vhost defaults to: "/" - - verify-ssl: indicate whether the server certificate is validated by the client or not ("true" by default) - - if ``ca-location`` is provided, and secure connection is used, the specified CA will be used, instead of the default one, to authenticate the broker - - amqp-exchange: the exchanges must exist and be able to route messages based on topics (mandatory parameter for AMQP0.9.1). Different topics pointing to the same endpoint must use the same exchange - - amqp-ack-level: no end2end acking is required, as messages may persist in the broker before delivered into their final destination. Three ack methods exist: - - - "none": message is considered "delivered" if sent to broker - - "broker": message is considered "delivered" if acked by broker (default) - - "routable": message is considered "delivered" if broker can route to a consumer - -.. tip:: The topic-name (see :ref:`radosgw-create-a-topic`) is used for the AMQP topic ("routing key" for a topic exchange). + - user/password: This defaults to "guest/guest". + - user/password: This must be provided only over HTTPS. Topic creation + requests will otherwise be rejected. + - port: This defaults to 5672 for unencrypted connections and 5671 for + SSL-encrypted connections. + - vhost: This defaults to "/". + - verify-ssl: This indicates whether the server certificate is validated by + the client. (This is "true" by default.) + - If ``ca-location`` is provided and a secure connection is used, the + specified CA will be used to authenticate the broker. The default CA will + not be used. + - amqp-exchange: The exchanges must exist and must be able to route messages + based on topics. This parameter is mandatory. Different topics that point + to the same endpoint must use the same exchange. + - amqp-ack-level: No end2end acking is required. Messages may persist in the + broker before being delivered to their final destinations. Three ack methods + exist: + + - "none": The message is considered "delivered" if it is sent to the broker. + - "broker": The message is considered "delivered" if it is acked by the broker (default). + - "routable": The message is considered "delivered" if the broker can route to a consumer. + +.. tip:: The topic-name (see :ref:`radosgw-create-a-topic`) is used for the + AMQP topic ("routing key" for a topic exchange). - Kafka endpoint - URI: ``kafka://[:@][: -The topic ARN in the response will have the following format: +The topic `ARN +`_ +in the response has the following format: :: @@ -227,7 +259,8 @@ The topic ARN in the response will have the following format: Get Topic Attributes ```````````````````` -Returns information about a specific topic. This includes push-endpoint information, if provided. +This returns information about a specific topic. This includes push-endpoint +information, if provided. :: @@ -236,7 +269,7 @@ Returns information about a specific topic. This includes push-endpoint informat Action=GetTopicAttributes &TopicArn= -Response will have the following format: +The response has the following format: :: @@ -270,22 +303,27 @@ Response will have the following format: -- User: name of the user that created the topic -- Name: name of the topic -- EndPoint: JSON formatted endpoint parameters, including: - - EndpointAddress: the push-endpoint URL - - EndpointArgs: the push-endpoint args - - EndpointTopic: the topic name that should be sent to the endpoint (may be different than the above topic name) - - HasStoredSecret: "true" if if endpoint URL contain user/password information. In this case request must be made over HTTPS. If not, topic get request will be rejected - - Persistent: "true" is topic is persistent -- TopicArn: topic ARN -- OpaqueData: the opaque data set on the topic +- User: the name of the user that created the topic. +- Name: the name of the topic. +- EndPoint: The JSON-formatted endpoint parameters, including: + - EndpointAddress: The push-endpoint URL. + - EndpointArgs: The push-endpoint args. + - EndpointTopic: The topic name to be sent to the endpoint (can be different + than the above topic name). + - HasStoredSecret: This is "true" if the endpoint URL contains user/password + information. In this case, the request must be made over HTTPS. The "topic + get" request will otherwise be rejected. + - Persistent: This is "true" if the topic is persistent. +- TopicArn: topic `ARN + `_. +- OpaqueData: The opaque data set on the topic. Get Topic Information ````````````````````` -Returns information about specific topic. This includes push-endpoint information, if provided. -Note that this API is now deprecated in favor of the AWS compliant `GetTopicAttributes` API. +This returns information about a specific topic. This includes push-endpoint +information, if provided. Note that this API is now deprecated in favor of the +AWS compliant `GetTopicAttributes` API. :: @@ -294,7 +332,7 @@ Note that this API is now deprecated in favor of the AWS compliant `GetTopicAttr Action=GetTopic &TopicArn= -Response will have the following format: +The response has the following format: :: @@ -319,15 +357,19 @@ Response will have the following format: -- User: name of the user that created the topic -- Name: name of the topic -- EndpointAddress: the push-endpoint URL -- EndpointArgs: the push-endpoint args -- EndpointTopic: the topic name that should be sent to the endpoint (may be different than the above topic name) -- HasStoredSecret: "true" if endpoint URL contain user/password information. In this case request must be made over HTTPS. If not, topic get request will be rejected -- Persistent: "true" is topic is persistent -- TopicArn: topic ARN -- OpaqueData: the opaque data set on the topic +- User: The name of the user that created the topic. +- Name: The name of the topic. +- EndpointAddress: The push-endpoint URL. +- EndpointArgs: The push-endpoint args. +- EndpointTopic: The topic name to be sent to the endpoint (which can be + different than the above topic name). +- HasStoredSecret: This is "true" if the endpoint URL contains user/password + information. In this case, the request must be made over HTTPS. The "topic + get" request will otherwise be rejected. +- Persistent: "true" if topic is persistent. +- TopicArn: topic `ARN + `_. +- OpaqueData: the opaque data set on the topic. Delete Topic ```````````` @@ -339,14 +381,16 @@ Delete Topic Action=DeleteTopic &TopicArn= -Delete the specified topic. +This deletes the specified topic. .. note:: - - Deleting an unknown notification (e.g. double delete) is not considered an error - - Deleting a topic does not automatically delete all notifications associated with it + - Deleting an unknown notification (for example, double delete) is not + considered an error. + - Deleting a topic does not automatically delete all notifications associated + with it. -The response will have the following format: +The response has the following format: :: @@ -367,7 +411,7 @@ List all topics associated with a tenant. Action=ListTopics -Response will have the following format: +The response has the following format: :: @@ -392,7 +436,9 @@ Response will have the following format: -- if endpoint URL contain user/password information, in any of the topic, request must be made over HTTPS. If not, topic list request will be rejected. +- If the endpoint URL contains user/password information in any part of the + topic, the request must be made over HTTPS. The "topic list" request will + otherwise be rejected. Notifications ~~~~~~~~~~~~~ @@ -481,3 +527,4 @@ pushed or pulled using the pubsub sync module. For example: .. _S3 Notification Compatibility: ../s3-notification-compatibility .. _AWS Create Topic: https://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html .. _Bucket Operations: ../s3/bucketops +.. _S3 CloudEvents Spec: https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/aws-s3.md