From 62a6a078b75debe637346040fd428734e398cf7c Mon Sep 17 00:00:00 2001 From: Robbie Trencheny Date: Sun, 15 May 2016 13:51:00 -0700 Subject: [PATCH] Add docs for AWS Lambda, SNS and SQS (#478) * Add docs for AWS Lambda, SNS and SQS * Improve SNS documentation --- source/_components/notify.aws_lambda.markdown | 77 ++++++++++++++++++ source/_components/notify.aws_sns.markdown | 42 ++++++++++ source/_components/notify.aws_sqs.markdown | 53 ++++++++++++ source/images/supported_brands/aws_lambda.png | Bin 0 -> 1310 bytes source/images/supported_brands/aws_sns.png | Bin 0 -> 1168 bytes source/images/supported_brands/aws_sqs.png | Bin 0 -> 1408 bytes 6 files changed, 172 insertions(+) create mode 100644 source/_components/notify.aws_lambda.markdown create mode 100644 source/_components/notify.aws_sns.markdown create mode 100644 source/_components/notify.aws_sqs.markdown create mode 100755 source/images/supported_brands/aws_lambda.png create mode 100755 source/images/supported_brands/aws_sns.png create mode 100755 source/images/supported_brands/aws_sqs.png diff --git a/source/_components/notify.aws_lambda.markdown b/source/_components/notify.aws_lambda.markdown new file mode 100644 index 00000000000..6f7a873448d --- /dev/null +++ b/source/_components/notify.aws_lambda.markdown @@ -0,0 +1,77 @@ +--- +layout: page +title: "AWS Lambda" +description: "Instructions how to invoke AWS Lambda functions from Home Assistant." +date: 2016-05-14 16:35 +sidebar: true +comments: false +sharing: true +footer: true +logo: aws_lambda.png +ha_category: Notifications +ha_release: 0.20 +--- + +The AWS Lambda notify platform enables invoking [AWS Lambda](https://aws.amazon.com/lambda/) functions. + +### Configuration + +```yaml +# Example configuration.yaml entry +notify: + platform: aws_lambda + name: NOTIFIER_NAME + aws_access_key_id: AWS_ACCESS_KEY_ID + aws_secret_access_key: AWS_SECRET_ACCESS_KEY + profile_name: AWS_PROFILE + region_name: 'us-east-1' + # Optional + context: + ... +``` + +Configuration variables: + +- **aws_access_key_id** (*Required if aws_secret_access_key is provided*): Your AWS Access Key ID. For more information, please read the [AWS General Reference regarding Security Credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html). If provided, you must also provide an `aws_secret_access_key` and must **not** provide a `profile_name`. +- **aws_secret_access_key** (*Required if aws_access_key_id is provided*): Your AWS Secret Access Key. For more information, please read the [AWS General Reference regarding Security Credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html). If provided, you must also provide an `aws_access_key_id` and must **not** provide a `profile_name`. +- **profile_name** (*Optional*): A credentials profile name. For more information, please see the [boto3 documentation section about credentials](http://boto3.readthedocs.io/en/latest/guide/configuration.html#shared-credentials-file). +- **region_name** (*Required*): The region identifier to connect to. The default is `us-east-1`. +- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. +- **context** (*Optional*): An optional dictionary you can provide to pass custom context through to the Lambda function. The `context` dictionary (if any) is combined with the same data available at the `/api/config` HTTP API route. + +### Usage + +AWS Lambda is a notify platform and thus can be controlled by calling the notify service [as described here](/components/notify/). It will invoke a Lambda for all targets given in the notification payload. A target can be formatted as a function name, an entire ARN ([Amazon Resource Name](http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)) or a partial ARN. For more information, please see the [boto3 docs](http://boto3.readthedocs.io/en/latest/reference/services/lambda.html#Lambda.Client.invoke). + +The Lambda event payload will contain everything passed in the service call payload. Here is an example payload that would be sent to Lambda: + +```json +{ + "title": "Test message!", + "target": "arn:aws:lambda:us-east-1:123456789012:function:ProcessKinesisRecords", + "data": { + "test": "okay" + }, + "message": "Hello world!" +} +``` + +The context will look like this: + +```json +{ + "hass": { + "components": ["recorder", "logger", "http", "logbook", "api", "frontend"], + "latitude": 44.1234, + "location_name": "Home", + "longitude": 5.5678, + "temperature_unit": "°C", + "time_zone": "Europe/Zurich", + "version": "0.20.0.dev0" + }, + "custom": { + "two": "three", + "test": "one" + } +} +``` diff --git a/source/_components/notify.aws_sns.markdown b/source/_components/notify.aws_sns.markdown new file mode 100644 index 00000000000..03e631f1bb0 --- /dev/null +++ b/source/_components/notify.aws_sns.markdown @@ -0,0 +1,42 @@ +--- +layout: page +title: "AWS SNS" +description: "Instructions how to publish messages to AWS SNS from Home Assistant." +date: 2016-05-14 16:35 +sidebar: true +comments: false +sharing: true +footer: true +logo: aws_sns.png +ha_category: Notifications +ha_release: 0.20 +--- + +The AWS SNS notify platform enables publishing to an [AWS SNS](https://aws.amazon.com/sns/) topic or application. + +### Configuration + +```yaml +# Example configuration.yaml entry +notify: + platform: aws_sns + name: NOTIFIER_NAME + aws_access_key_id: AWS_ACCESS_KEY_ID + aws_secret_access_key: AWS_SECRET_ACCESS_KEY + profile_name: AWS_PROFILE + region_name: 'us-east-1' +``` + +Configuration variables: + +- **aws_access_key_id** (*Required if aws_secret_access_key is provided*): Your AWS Access Key ID. For more information, please read the [AWS General Reference regarding Security Credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html). If provided, you must also provide an `aws_secret_access_key` and must **not** provide a `profile_name`. +- **aws_secret_access_key** (*Required if aws_access_key_id is provided*): Your AWS Secret Access Key. For more information, please read the [AWS General Reference regarding Security Credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html). If provided, you must also provide an `aws_access_key_id` and must **not** provide a `profile_name`. +- **profile_name** (*Optional*): A credentials profile name. For more information, please see the [boto3 documentation section about credentials](http://boto3.readthedocs.io/en/latest/guide/configuration.html#shared-credentials-file). +- **region_name** (*Required*): The region identifier to connect to. The default is `us-east-1`. +- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. + +### Usage + +AWS SNS is a notify platform and thus can be controlled by calling the notify service [as described here](/components/notify/). It will publish a message to all targets given in the notification payload. A target must be a SNS topic or endpoint ARN ([Amazon Resource Name](http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)). For more information, please see the [boto3 docs](http://boto3.readthedocs.io/en/latest/reference/services/sns.html#SNS.Client.publish). + +If one exists, the SNS Subject will be set to the title. All attributes from the payload except message will be sent as stringified message attributes. diff --git a/source/_components/notify.aws_sqs.markdown b/source/_components/notify.aws_sqs.markdown new file mode 100644 index 00000000000..b89bdbc8a06 --- /dev/null +++ b/source/_components/notify.aws_sqs.markdown @@ -0,0 +1,53 @@ +--- +layout: page +title: "AWS SQS" +description: "Instructions how to publish messages to AWS SQS from Home Assistant." +date: 2016-05-14 16:35 +sidebar: true +comments: false +sharing: true +footer: true +logo: aws_sqs.png +ha_category: Notifications +ha_release: 0.20 +--- + +The AWS SQS notify platform enables publishing to an [AWS SQS](https://aws.amazon.com/sqs/) message queue. + +### Configuration + +```yaml +# Example configuration.yaml entry +notify: + platform: aws_sqs + name: NOTIFIER_NAME + aws_access_key_id: AWS_ACCESS_KEY_ID + aws_secret_access_key: AWS_SECRET_ACCESS_KEY + profile_name: AWS_PROFILE + region_name: 'us-east-1' +``` + +Configuration variables: + +- **aws_access_key_id** (*Required if aws_secret_access_key is provided*): Your AWS Access Key ID. For more information, please read the [AWS General Reference regarding Security Credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html). If provided, you must also provide an `aws_secret_access_key` and must **not** provide a `profile_name`. +- **aws_secret_access_key** (*Required if aws_access_key_id is provided*): Your AWS Secret Access Key. For more information, please read the [AWS General Reference regarding Security Credentials](http://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html). If provided, you must also provide an `aws_access_key_id` and must **not** provide a `profile_name`. +- **profile_name** (*Optional*): A credentials profile name. For more information, please see the [boto3 documentation section about credentials](http://boto3.readthedocs.io/en/latest/guide/configuration.html#shared-credentials-file). +- **region_name** (*Required*): The region identifier to connect to. The default is `us-east-1`. +- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. + +### Usage + +AWS SQS is a notify platform and thus can be controlled by calling the notify service [as described here](/components/notify/). It will publish a message to the queue for all targets given in the notification payload. A target must be a SQS topic URL. For more information, please see the [SQS docs](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/ImportantIdentifiers.html). + +The SQS event payload will contain everything passed in the service call payload. SQS payloads will be published as stringified JSON. All attributes from the payload except message will also be sent as stringified message attributes. Here is an example message that would be published to the SQS queue: + +```json +{ + "title": "Test message!", + "target": "http://sqs.us-east-1.amazonaws.com/123456789012/queue2", + "data": { + "test": "okay" + }, + "message": "Hello world!" +} +``` diff --git a/source/images/supported_brands/aws_lambda.png b/source/images/supported_brands/aws_lambda.png new file mode 100755 index 0000000000000000000000000000000000000000..40608d21c75afe29ceb6dfa2e6479d8068b91ad4 GIT binary patch literal 1310 zcmV+(1>yRMP)SscfIGaV?Uf<;_m z4Tl0Tnh;G7>uUC5@no_G-FV)mgrf%~9zCE3&xROJ#!znD=!B6owIvu02(|!SBN$M@XfhR$WHt~@3^1kwlFSBD z0T@#NNe2MLgNJ*?fam~opn&89fbS~@MW^Vy-eLqBt7R0E!Mds`AS;8ZDWH9WQ4=!{ zZ-A8jMw!)(WB`sg0X|F!uYblCLdO_08BhS9XJ1ZQG76+bVn&K!8z)E;(`$79RJrff z5ta1H5Fp7YkV^ldrS)X=_kZGE6Tuh)q{qjM840@%S*n-9P?rzlAu81bkjyd}{6L_d zrU1+Uq?Ga@_yMxVFt(Y=moZObH^VESf+(hxsb#!c|6!K{RyTKfA3++RVYvpi3=e>O zvf#i`RQmV-1neZ!HT@fk6~X*EyAE>*=Xh%aeADHIp7y5fx$VJdTHHv&FK<4VWo<46 z`Z`_E+wO$E4wpT_9CbGYal}x>^lN=;>>~~NOWxrFjr5vjsG+; z8@~44*B%wl1@%Y~HtT=>T-nJsk`a@$v?)D!xGPGk2chuoe5a$^0|??eo_ca4Q==lqu-56vLNH>>%y;ucDxf-7e{R1dNd#)L8k6%p z)=K1Xrvw|08=Q6P-A){m0f1=Xv9nkFl_nH zdYi8cFbws6<@9tPZ4_WwI@j%nwq}O_!xAkXa64rIM&vOS>W|qtY$ehHOs-!3w_VYz zW?O-ofB!M|_ew&TQl27D=C($KkNHwGN!~AO zv2Tk6FE0XN8x)yup|kyAzsvS5`NFNG$q~ftm1g9q`P8GP{%ZWl%aUNudYi}n4_}9K z`{)%d9joyc(z0M!8Vb#Z%iYu2)dkB73-$uTQgZ4(b72u_W#Jtpwl~4C_zJHQe1j-S%h_{oO-boJKaiaIaikas*!_qQ zK97j(sK9GmIA6)t8YpHWnRV4f>>QPhm=0WRiuMhjNMW5gK%z@iv5>4 z22${QY=u#bMTbJRFfAq!TNIH-fEWQoeyHeHN=0j#R3^eI=IRy5UUseb+bh`gLUY)( zGe~%1dX1o1Zqp0hrj+NTH9&hX@Bu=3AT2RMs^(*I0hzs-Up0YL&H1W;xBCND$U%b9YO#P7fEW(fMkThCGziGHn~)kv6ioqQI+%Pw^|sM*-KgHS#{MM00An^N U<2fcUP5=M^07*qoM6N<$f+|i_YybcN literal 0 HcmV?d00001 diff --git a/source/images/supported_brands/aws_sns.png b/source/images/supported_brands/aws_sns.png new file mode 100755 index 0000000000000000000000000000000000000000..1a04bd8e0df5544afba4998471436cc87a7527e5 GIT binary patch literal 1168 zcmV;B1aJF^P)1RCwC#+`mr~aTEaXch@UFN?WcX zN=OLB$;5#s{sFcQP9|Pr!d&8_aq3{AlaQEb;vi1C0fUQ)N!?9aCkF>$bU`9WKm{vp zfwuhcz2keN9@o-dDR-9llJl;;qrLm^{l51~dIGp4p4_;vy}SE7>X!47oIZhj!y|<8 zI1~&-uU@%KPo;4gzy10_`b@$YAh_tG1YtnH7~v?8Ts9l3kE0jTr^OBnj%nr_Y)=9!{t#)f={eB)cHB zUeNr~GR!Z22M1wn0m*fsq)xc(x;h87LRD%C&=HvDHxpr(R2fHsq_XJ}79aoPVy;sH zrAqVh%hzwPxU%}fPHu2fj;SjLDFz5Ganpfev1k{1LIiUbMvzhF6S4q_14lWKCbI)q zC5B-bhG7_nVHk#C7=~dO4u)YEhG7_nVHk#C7=~dOhT&ishG7_nVHk#C7=~dOhB_^vJ@9w5fhX>NM}`C9#BnugJnjz#z~A1cZ~xxN!s^<3dTHec zy#d{z6)}I?l17{2@qpKJFiTzVtxbYRR70o<#*8D&5?tyHl~1W5<0c9`Zf3VsiUhiR zu!$f>w0jj8?CEw3Ow7)W7M98PQSuq(oN?OT+uMib-&teVlf76e z0%Y@>kloyZU+bC7Mm|r&I$UkUPys0H?0^qn!)6hPo!V_V74RtEq|7*!X9mx!Ru`4P z6Q00osPtvXs)2lNKI?2ML}qkRlcJxXw+=I7}* zzVat`q(`7BDXL+n)8`xQRzsN%e?XtIYq?E5Ul}NR($8;0u28J^w5DCr;2}=Z3MaQ+ zG+)%q^6DT^V*;#V5b)mqe$8bW-($)(ov%pRLjq{ZxLCR<8a?9iM1>KTsP@`4f-FW~ zr5JDYTAJS0iu|KtFLVogqWAcl9IJBdKRuLH^ai^i100RK*CBA!Uyrp3P0000#(~ literal 0 HcmV?d00001 diff --git a/source/images/supported_brands/aws_sqs.png b/source/images/supported_brands/aws_sqs.png new file mode 100755 index 0000000000000000000000000000000000000000..ffb40ee6bf94df8af5dcda722997de71820da69b GIT binary patch literal 1408 zcmV-`1%LX9P)c&thYp05-W0k4hQ2&97Oj$c+B~_zHky^=V6j7SCIq1+r z5V4JafNh+<@5>!M+h_aE_kP*jS9*H)&ItH^{QaKKcNhRg;+rp)Q``4eQmXtunhGFf z`kIW}pMCTe?%E*ZPG)t}IF~SX5Nn?aV}(>8O$Cq+Fj9du6+n8xNCDDR0C5Q;6i8D6 z#3PIlAWa33K4G{5X)1vDgy90DsQ|(VhAEJy0tjOmCP11BAe>-)0ck3LaE9p%NK*ks z5R4}vO$89aFs^_!6+k4xbOq8>0Feyi2&55^IGNXFfz;}+p>li*rAi$x&5pynS0-WM z;snH|beTYF_|tEQMmecA2*fEA%XPYK#q)9rp8s8<+jG-naBX3dKt<@bz(9+;!k(65 z`At<|bzqhBiv3q7bUb`=NUH~{2&)N)h|oo}2%`9je6bEsi%0PE&m+3FfOxi?E}}(P z2eupUmeWPI2H$e>bi$ z`0UqC8<4}f-Z)#o%vBw~e)*lLrZrX?8S5Y4Onmay=V^p_Vyl>3W_2^GB#b@rrOT0~ z$A0?tup>Ypam$=PweQ@%w*q#k7C6Jty(L#LWm4)pq^xl+pPbUt$8CGG!U&9b54es8 zzP0h5e}1DK#<0+;|M zfI06GyjLP`7|r=d+dAtCCNefkFCulj>@Z-7LuPgJf$xgJ%a5&B*D&l*62tL2aIeI< zwi1HjNW|J7`|$b&PKmK|_2gY17L7-BQCRlUH*@48UR`O?+f!j$_XNX2G&?;I= zU!_ao#QBBG4kM%t!z5h8tePkr)W_ z|408?AC(0p5vB>m3S~ZCECI$5q$iAMAb~JlL0rR#0ulh@3dA!EZy=5^o