iSharkFly-Docs/OpenSearch-Docs-Cn
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
447cb1948de1b11594ec6de5310b10e41eb82292
OpenSearch-Docs-Cn/_notifications-plugin/api.md
T
keithhc2 447cb1948d Added notifications plugin 
Signed-off-by: keithhc2 <[email protected]>
2022-03-24 09:31:34 -07:00

18 KiB
Raw Blame History

layout, title, nav_order, has_children, redirect_from
layout title nav_order has_children redirect_from
default API 50 false

Notifications API

If you don’t want to use OpenSearch Dashboards, you can use the REST API to create, configure, and delete notification channels, email senders, and email recipient groups, as well as send test messages.

If you want to programmatically define your notifications channels and sources for versioning and reuse, you can use the REST API to create, configure, and delete notification channels, email senders, and email recipient groups, as well as send test messages.

Table of contents

  1. TOC {:toc}

List supported features

Lists supported channel types and email limitations, such as accepted file sizes and connect timeouts.

Sample Request

GET /_plugins/_notifications/features

Sample Response

{
  "config_type_list" : [
  "slack",
  "chime",
  "webhook",
  "email",
  "sns",
  "smtp_account",
  "email_group"
  ],
  "plugin_features" : {
  "opensearch.notifications.spi.email.sizeLimit" : "10000000",
  "opensearch.notifications.spi.email.minimumHeaderLength" : "160",
  "opensearch.notifications.spi.http.maxConnections" : "60",
  "opensearch.notifications.spi.http.maxConnectionPerRoute" : "20",
  "opensearch.notifications.spi.http.connectionTimeout" : "5000",
  "opensearch.notifications.spi.http.socketTimeout" : "50000",
  "opensearch.notifications.spi.tooltip_support" : "false"
  }
}

Create channel

Creates a notification channel.

Sample Request

POST /_plugins/_notifications/configs/
{
  "id": "sample-id",
  "name": "sample-name",
  "config": {
    "name": "Sample Slack Channel",
    "description": "This is a Slack channel",
    "config_type": "slack",
    "feature_list": [
      "reports"
    ],
    "is_enabled": true,
    "slack": {
      "url": "https://sample-slack-webhook"
    }
  }
}

The create channel API operation accepts the following fields in its request body:

Field Data Type Description Required
config Object Contains all of relevant information such as channel name, configuration type, and plugin source. Yes
name String Name of the channel. Yes
description String The channel's description. No
config_type String The destination of your notification. Valid options are chime, sns, slack, email, and webhook. Yes
feature_list Array of strings The OpenSearch plugins you want to associate with the channel. Valid options are alerting, reports, and index_management. Yes
is_enabled Boolean Whether to enable to channel to receive and send notifications. Default is true. No

The create channel operation accepts multiple config_types as possible notification destinations, so just follow the format for your preferred config_type.

"sns": {
  "topic_arn": "<arn>",
  "role_arn": "<arn>" //optional
}
"slack": {
  "url": "https://sample-chime-webhoook"
}
"chime": {
  "url": "https://sample-amazon-chime-webhoook"
}
"webhook" : {
  "url" : "https://sample-webhook",
  "header_params" : {
    "Content-Type" : "application/json"
  },
  "method" : "POST"
}
"email" : {
  "email_account_id" : "<sample-email-account-id>",
  "recipient_list" : [
    "[email protected]"
  ],
  "email_group_id_list" : [
    "<email-group-id>"
  ]
}

The following example demonstrates how to create a channel using email as a config_type:

POST /_plugins/_notifications/configs/
{
  "id": "sample-email-id",
  "name": "sample-name",
  "config": {
    "name": "Sample Email Channel",
    "description": "Sample email description",
    "config_type": "email",
    "feature_list": [
      "reports"
    ],
    "is_enabled" : true,
    "email" : {
    "email_account_id" : "<email_account_id>",
    "recipient_list" : [
      "[email protected]"
    ]
  }
  }
}

Sample Response

{
  "config_id" : "<config_id>"
}

Send test notification

Sends a test notification.

Sample Request

GET _plugins/_notifications/events

Sample Response

{
  "event_id" : "<event_id>"
}

List all sent notifications

Lists all sent notifications.

Sample Request

GET _plugins/_notifications/events

Sample Response

{
  "start_index" : 0,
  "total_hits" : 10,
  "total_hit_relation" : "eq",
  "event_list" : [
  {
    "event_id" : "<event_id>",
    "last_updated_time_ms" : 1629226098683,
    "created_time_ms" : 1629226098222,
    "tenant" : "__user__",
    "event" : {
    "event_source" : {
      "title" : "Sample notification event",
      "reference_id" : "<reference_id>",
      "feature" : "reporting",
      "severity" : "info",
      "tags" : [ ]
    },
    "status_list" : [
      {
      "config_id" : "<config_id>",
      "config_type" : "webhook",
      "config_name" : "This is a config name",
      "email_recipient_status" : [ ],
      "delivery_status" : {
        "status_code" : "200",
        "status_text" : "Example status text"
      }
      }
    ]
    }
  }
  ]
}

To filter down your results, specify the following parameters in your request path. All parameters are optional.

Parameter Description
event_id_list Comma-separated list of notification event IDs to retrieve.
from_index The starting index to search from.
max_items The maximum number of items the request should return.
sort_order Specifies the direction to sort results in. Valid options are asc and desc.
sort_field Field to sort results with.
last_updated_time_ms The unix time in milliseconds of when the channel was last updated.
created_time_ms The unix time in milliseconds of when the channel was created.
event_source.reference_id The notification event's reference ID.
event_source.feature The OpenSearch plugin that triggered the notification event.
event_source.severity The severity of the of the notification event. Valid options are info and high.
event_source.tags Any tags associated with the notification event.
event_source.title The notification event's title.
status_list.config_id The channel's config ID.
status_list.config_type The channel's notification type. Valid options are slack, chime, sns, email, and webhook.
status_list.config_name The channel's name.
status_list.delivery_status.status_code The notification event's delivery status code.
status_list.delivery_status.status_text Status text related to the notification's delivery status.
status_list.email_recipient_status.recipient Any statuses associated with email recipients.
status_list.email_recipient_status.delivery_status.status_code Any status codes associated with email recipients.
status_list.email_recipient_status.delivery_status.status_text Status text related to email recipients' delivery statuses.

For example, the following request returns a notification sent to Slack that was triggered by the Alerting plugin.

Sample Request

GET _plugins/_notifications/events?status_list.config_type=slack&event_source.feature=alerting

Sample Response

{
  "start_index" : 0,
  "total_hits" : 1,
  "total_hit_relation" : "eq",
  "event_list" : [
  {
    "event_id" : "<event_id>",
    "last_updated_time_ms" : 1630354617088,
    "created_time_ms" : 1630354617082,
    "tenant" : "__user__",
    "event" : {
    "event_source" : {
      "title" : "Sample notification event",
      "reference_id" : "<reference_id>",
      "feature" : "alerting",
      "severity" : "info",
      "tags" : [ ]
    },
    "status_list" : [
      {
      "config_id" : "<config_id>",
      "config_type" : "slack",
      "config_name" : "Sample Slack Channel",
      "email_recipient_status" : [ ],
      "delivery_status" : {
        "status_code" : "200",
        "status_text" : "Example status text"
      }
      }
    ]
    }
  }
  ]
}

List all channels

Lists all notification channels.

Sample Request

GET _plugins/_notifications/configs

Sample Response*

{
  "start_index" : 0,
  "total_hits" : 3,
  "total_hit_relation" : "eq",
  "config_list" : [
  {
    "config_id" : "f8gxMnsBgleqOc4sp278",
    "last_updated_time_ms" : 1628634720251,
    "created_time_ms" : 1628634720251,
    "tenant" : "__user__",
    "config" : {
    "name" : "Testing Gmail Channel",
    "description" : "",
    "config_type" : "smtp_account",
    "feature_list" : [
      "alerting",
      "index_management",
      "reports"
    ],
    "is_enabled" : true,
    "smtp_account" : {
      "host" : "smtp.gmail.com",
      "port" : 80,
      "method" : "ssl",
      "from_address" : "[email protected]"
    }
    }
  },
  {
    "config_id" : "g20bN3sBUeso9oKNgb8C",
    "last_updated_time_ms" : 1628717154562,
    "created_time_ms" : 1628717154562,
    "tenant" : "__user__",
    "config" : {
    "name" : "Slack Channel 1",
    "description" : "This is an optional description",
    "config_type" : "slack",
    "feature_list" : [
      "reports"
    ],
    "is_enabled" : true,
    "slack" : {
      "url" : "https://hooks.slack.com/a-sample-url"
    }
    }
  },
  {
    "config_id" : "0W0kN3sBUeso9oKNur-_",
    "last_updated_time_ms" : 1628717759167,
    "created_time_ms" : 1628717759167,
    "tenant" : "__user__",
    "config" : {
    "name" : "Another Sample Slack Channel",
    "description" : "Sample description",
    "config_type" : "slack",
    "feature_list" : [
      "reports"
    ],
    "is_enabled" : true,
    "slack" : {
      "url" : "https://hooks.slack.com/another-sample-url"
    }
    }
  }
  ]
}

You can include query parameters in your request path to filter the notification channels this request returns. All parameters are optional.

Parameter Description
config_id Unique identifier of a channel.
config_id_list Comma-separated list of channel IDs.
from_index The starting index to search from.
max_items The maximum amount of items to return in your request.
sort_order Specifies the direction to sort results in. Valid options are asc and desc.
sort_field Field to sort results with.
last_updated_time_ms The unix time in milliseconds of when the channel was last updated.
created_time_ms The unix time in milliseconds of when the channel was created.
is_enabled Whether the channel is enabled.
config_type The channel type. Valid options are slack, chime, sns, email, and webhook.
feature_list The OpenSearch plugin associated with the channel.
name The channel's name.
description The channel's description.
email.email_account_id The sender emails the channel uses.
email.email_group_id_list The email groups the channel uses.
smtp_account.method The email encryption method.
slack.url The Slack channel's URL.
chime.url The Amazon Chime connection's URL.
webhook.url The webhook's URL.
email.recipient_list The channel's recipient list.
email_group.recipient_list The channel's list of email recipient groups.
smtp_account.host The domain of the smtp account.
smtp_account.from_address The email account's sender address.
smtp_account.recipient_list The channel's recipient list.
sns.topic_arn The Amazon SNS topic's ARN.
sns.role_arn The Amazon SNS topic's role ARN.
ses_account.region The Amazon SES account's region.
ses_account.role_arn The Amazon SES account's role ARN.
ses_account.from_address The Amazon SES account's sender email address.

Get channel configuration

Get a channel’s configuration by config_id.

Sample Request

GET _plugins/_notifications/configs/<config_id>

Sample Response

{
  "start_index" : 0,
  "total_hits" : 1,
  "total_hit_relation" : "eq",
  "config_list" : [
  {
    "config_id" : "<config_id>",
    "last_updated_time_ms" : 1628634720251,
    "created_time_ms" : 1628634720251,
    "tenant" : "__user__",
    "config" : {
    "name" : "Testing Gmail Channel",
    "description" : "",
    "config_type" : "smtp_account",
    "feature_list" : [
      "alerting",
      "index_management",
      "reports"
    ],
    "is_enabled" : true,
    "smtp_account" : {
      "host" : "smtp.gmail.com",
      "port" : 80,
      "method" : "ssl",
      "from_address" : "[email protected]"
    }
    }
  }
  ]
}

Update channel configuration

Updates a channel’s configuration.

Sample Request

PUT _plugins/_notifications/configs/<config_id>
{
  "config": {
    "name": "Slack Channel",
    "description": "This is an updated channel configuration",
    "config_type": "slack",
    "feature_list": [
      "index_management"
    ],
    "is_enabled": true,
    "slack": {
      "url": "https://hooks.slack.com/sample-url"
    }
  }
}

Sample Response

{
  "config_id" : "<config_id>"
}

Delete channel

Deletes a channel.

Sample Request

DELETE /_plugins/_notifications/configs/<config_id>

Sample Response*

{
  "delete_response_list" : {
  "<config_id>" : "OK"
  }
}

You can also submit a comma-separated list of channel IDs you want to delete, and OpenSearch deletes all of the specified notification channels.

Sample Request

DELETE /_plugins/_notifications/configs/?config_id_list=<config_id1>,<config_id2>,<config_id3>...

Sample Response

{
  "delete_response_list" : {
  "<config_id1>" : "OK",
  "<config_id2>" : "OK",
  "<config_id3>" : "OK"
  }
}

Create email sender

Creates an email sender for use when creating an email channel.

Sample Request

POST _plugins/_notifications/configs
{
  "config": {
  "name": "test_email_08-20-2021",
  "config_type": "smtp_account",
   "feature_list" : [
    "alerting"
   ],
  "is_enabled" : true,
  "smtp_account": {
     "host": "smtp.gmail.com",
    "port": 465,
    "method": "ssl",
    "from_address": "[email protected]"
  }
  }
}

Sample Response

{
  "config_id" : "<config_id>"
}

Get email sender

Retrieves an email sender.

Sample Request

GET _plugins/_notifications/configs/<config_id>

Sample Response

{
  "start_index" : 0,
  "total_hits" : 1,
  "total_hit_relation" : "eq",
  "config_list" : [
  {
    "config_id" : "6j2jZXsBnB7tlos71NNu",
    "last_updated_time_ms" : 1629497886595,
    "created_time_ms" : 1629497840749,
    "tenant" : "__user__",
    "config" : {
    "name" : "Sample_Email_2021",
    "description" : "",
    "config_type" : "smtp_account",
    "feature_list" : [
      "alerting"
    ],
    "is_enabled" : true,
    "smtp_account" : {
      "host" : "smtp.gmail.com",
      "port" : 465,
      "method" : "ssl",
      "from_address" : "[email protected]"
    }
    }
  }
  ]
}

Update email sender

Updates an email sender with new fields.

Sample Request

PUT _plugins/_notifications/configs/<config_id>
{
  "config": {
  "name": "This is a new name",
  "config_type": "smtp_account",
   "feature_list" : [
    "alerting"
   ],
  "is_enabled" : false,
  "smtp_account": {
     "host": "smtp.gmail.com",
    "port": 587,
    "method": "ssl",
    "from_address": "[email protected]"
  }
  }
}

Sample Response

{
  "config_id" : "<config_id>"
}

Delete email sender

Deletes an email sender.

Sample Request

DELETE _plugins/_notifications/configs/<config_id>

Sample Response

{
  "delete_response_list" : {
  "<config_id>" : "OK"
  }
}

To delete multiple email senders, specify all of the necessary IDs in a comma-separated list.

Sample Request

DELETE _plugins/_notifications/configs/?config_id_list=<config_id1>,<config_id2>,<config_id3>

Sample Response

{
  "delete_response_list" : {
  "<config_id1>" : "OK",
  "<config_id2>" : "OK",
  "<config_id3>" : "OK",
  "<config_id4>" : "OK"
  }
}

Create email recipient group

Creates an email recipient group

Sample Request

POST _plugins/_notifications/configs/
{
  "config": {
    "name": "Sample Email Group Name",
    "description": "This is an email group",
    "config_type": "email_group",
    "feature_list": [
      "alerting"
    ],
    "is_enabled": true,
    "email_group": {
      "recipient_list": [
        "[email protected]"
      ]
    }
  }
}

Sample Response

{
  "config_id" : "<config_id>"
}

Get email recipient group

Returns an email recipient group

Sample Request

GET _plugins/_notifications/configs/<config_id>

Sample Response

{
  "start_index" : 0,
  "total_hits" : 1,
  "total_hit_relation" : "eq",
  "config_list" : [
  {
    "config_id" : "<config_id>",
    "last_updated_time_ms" : 1630106022155,
    "created_time_ms" : 1630106022155,
    "tenant" : "__user__",
    "config" : {
    "name" : "Sample Email Group Name",
    "description" : "This is an email group",
    "config_type" : "email_group",
    "feature_list" : [
      "alerting"
    ],
    "is_enabled" : true,
    "email_group" : {
      "recipient_list" : [
      "[email protected]"
      ]
    }
    }
  }
  ]
}

Update email recipient group

Updates an email recipient group

Sample Request

PUT _plugins/_notifications/configs/<config_id>
{
  "config": {
    "name": "This is an updated email group",
    "description": "This is an updated description",
    "config_type": "email_group",
    "feature_list": [
      "alerting"
    ],
    "is_enabled": true,
    "email_group": {
      "recipient_list": [
        "[email protected]"
      ]
    }
  }
}

Sample Response

{
  "config_id" : "<config_id>"
}

Delete email recipient group

Deletes an email recipient group

Sample Request

DELETE _plugins/_notifications/configs/<congid_id>

Sample Response

{
  "delete_response_list" : {
  "<config_id>" : "OK"
  }
}

The delete email group operation also supports deleting multiple email groups with one request.

Sample Request

DELETE _plugins/_notifications/configs/?config_id_list=<config_id1>,<config_id2>

Sample Response

{
  "delete_response_list" : {
  "<config_id1>" : "OK",
  "<config_id2>" : "OK"
  }
}
Reference in New Issue View Git Blame Copy Permalink