Updated on 2023-07-04 GMT+08:00

Getting Started

Scenarios

This topic describes how to publish a message to a topic by calling APIs.

For details about how to call APIs, see Calling APIs.

The token obtained from IAM is valid for only 24 hours. If you want to use one token for authentication, you can cache it to avoid frequently calling the IAM API.

Involved APIs

If you use a token for authentication, you must obtain the token and add X-Auth-Token to the request header of the API when making a call.

  • IAM API to obtain a token
  • SMN API to create a topic
  • SMN API to add subscriptions
  • SMN API to publish messages

Procedure

  1. Obtain the token by referring to Authentication.
  2. Send a request POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics to create a topic.
    1. Add X-Auth-Token to the request header.
    2. Specify the following parameters in the request body:
      {
          "name": "test_topic_v2", //(Mandatory) Topic name
          "display_name": "test"  //(Optional) Display name
      }

      If the request is successful, a request ID (request_id) and topic URN (topic_urn) are returned.

      If the request fails, an error code and error message are returned. For details, see Error Codes

  3. Send request POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/{topic_urn}/subscriptions to add subscriptions.

    Set topic_urn based on the response in 2.b.

    1. Add X-Auth-Token to the request header.
    2. Specify the following parameters in the request body:
      {
          "protocol": "email", //(Mandatory) Subscription protocol 
          "endpoint": "xxx@xx.com", //(Mandatory) Email address
          "remark": "Subscription" //(Optional) Description 
      }

      If the request is successful, a request ID (request_id) and subscription URN (subscription_urn) are returned.

      If the request fails, an error code and error message are returned. For details, see Error Codes.

      You can add multiple subscriptions to a topic. For details, see Adding a Subscription.

    3. The subscription endpoint receives a confirmation message, and you must confirm the subscription in the email.
  4. Send request POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/{topic_urn}/publish.
    1. Add X-Auth-Token to the request header.
    2. Specify the following parameters in the request body:
      {
         "subject":"test message v2", //(Optional) Message subject, which is displayed in email messages
         "message": "Message test message v2." //(Mandatory) Message to be published 
      }

      If the request is successful, a request ID (request_id) and message ID (message_id) are returned.

      If the request fails, an error code and error message are returned. For details, see Error Codes.

      Only confirmed subscription endpoints can receive the message you publish.