Konektor Notifikasi Twilio - AWS IoT Greengrass
PersyaratanParameterData inputData outputContoh PenggunaanLisensiChangelogLihat juga

AWS IoT Greengrass Version 1 memasuki fase umur panjang pada 30 Juni 2023. Untuk informasi selengkapnya, lihat kebijakan AWS IoT Greengrass V1 pemeliharaan. Setelah tanggal ini, tidak AWS IoT Greengrass V1 akan merilis pembaruan yang menyediakan fitur, penyempurnaan, perbaikan bug, atau patch keamanan. Perangkat yang berjalan AWS IoT Greengrass V1 tidak akan terganggu dan akan terus beroperasi dan terhubung ke cloud. Kami sangat menyarankan Anda bermigrasi ke AWS IoT Greengrass Version 2, yang menambahkan fitur baru yang signifikan dan dukungan untuk platform tambahan.

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Konektor Notifikasi Twilio

Awas

Konektor ini telah pindah kefase kehidupan yang panjang, danAWS IoT Greengrasstidak akan merilis pembaruan yang menyediakan fitur, penyempurnaan untuk fitur yang ada, patch keamanan, atau perbaikan bug. Untuk informasi selengkapnya, lihat AWS IoT Greengrass Version 1kebijakan pemeliharaan.

Konektor Notifikasi Twilio melakukan panggilan telepon otomatis atau mengirim pesan teks melalui Twilio. Anda dapat menggunakan konektor ini untuk mengirim notifikasi dalam menanggapi peristiwa dalam grup Greengrass. Untuk panggilan telepon, konektor dapat meneruskan pesan suara ke penerima.

Konektor ini menerima informasi pesan Twilio pada topik MQTT, dan kemudian memicu notifikasi Twilio.

catatan

Untuk tutorial yang menunjukkan cara menggunakan konektor notifikasi Twilio, lihat Memulai dengan konektor Greengrass (konsol) atau Memulai dengan konektor Greengrass (CLI).

Konektor ini memiliki versi berikut.

Versi

ARN

5

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/5

4

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4

3

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/3

2

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/2

1

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/1

Untuk informasi tentang perubahan versi, lihat Changelog.

Persyaratan

Konektor ini memiliki persyaratan sebagai berikut:

Version 4 - 5

  • AWS IoT Greengrass perangkat lunak Core v1.9.3 atau yang lebih baru. AWS IoT Greengrass harus dikonfigurasi untuk mendukung rahasia lokal, seperti yang dijelaskan dalam Persyaratan Rahasia.

    catatan

    Persyaratan ini mencakup mengizinkan akses ke rahasia Secrets Manager Anda. Jika Anda menggunakan peran layanan default Greengrass, Greengrass memiliki izin untuk mendapatkan nilai-nilai rahasia dengan nama yang dimulai dengan greengrass-.

  • Python versi 3.7 atau 3.8 diinstal pada perangkat core dan ditambahkan ke variabel lingkungan PATH.

    catatan

    Untuk menggunakan Python 3.8, jalankan perintah berikut untuk membuat link simbolik dari folder instalasi default Python 3.7 ke binari Python 3.8 yang diinstal.

    sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7

    Ini mengonfigurasi perangkat Anda untuk memenuhi persyaratan Python untuk AWS IoT Greengrass.

  • Twilio account SID, token auth, dan nomor telepon berkemampuan Twilio. Setelah Anda membuat proyek Twilio, nilai-nilai ini tersedia dalam dasbor proyek.

    catatan

    Anda dapat menggunakan akun percobaan Twilio. Jika menggunakan akun uji coba, Anda harus menambahkan nomor telepon penerima selain Twilio ke daftar nomor telepon terverifikasi. Untuk informasi lebih lanjut, lihat Cara Bekerja dengan Akun Trial Twilio Gratis.

  • Sebuah rahasia jenis teks dalam AWS Secrets Manager yang menyimpan token auth Twilio. Untuk informasi lebih lanjut, lihat Membuat rahasia dasar dalam AWS Secrets Manager Panduan Pengguna.

    catatan

    Untuk membuat rahasia dalam konsol Secrets Manager, masukkan token Anda pada tab Plaintext ini. Jangan sertakan tanda kutip atau pemformatan lainnya. Dalam API, tentukan token sebagai nilai untuk properti SecretString ini.

  • Sebuah sumber daya rahasia dalam grup Greengrass yang mereferensikan rahasia Secrets Manager. Untuk informasi selengkapnya, lihat Men-deploy rahasia ke AWS IoT Greengrass core.

Versions 1 - 3

  • AWS IoT Greengrass perangkat lunak Core v1.7 atau yang lebih baru. AWS IoT Greengrass harus dikonfigurasi untuk mendukung rahasia lokal, seperti yang dijelaskan dalam Persyaratan Rahasia.

    catatan

    Persyaratan ini mencakup mengizinkan akses ke rahasia Secrets Manager Anda. Jika Anda menggunakan peran layanan default Greengrass, Greengrass memiliki izin untuk mendapatkan nilai-nilai rahasia dengan nama yang dimulai dengan greengrass-.

  • Python versi 2.7 diinstal pada perangkat core dan ditambahkan ke variabel lingkungan PATH.

  • Twilio account SID, token auth, dan nomor telepon berkemampuan Twilio. Setelah Anda membuat proyek Twilio, nilai-nilai ini tersedia dalam dasbor proyek.

    catatan

    Anda dapat menggunakan akun percobaan Twilio. Jika menggunakan akun uji coba, Anda harus menambahkan nomor telepon penerima selain Twilio ke daftar nomor telepon terverifikasi. Untuk informasi lebih lanjut, lihat Cara Bekerja dengan Akun Trial Twilio Gratis.

  • Sebuah rahasia jenis teks dalam AWS Secrets Manager yang menyimpan token auth Twilio. Untuk informasi lebih lanjut, lihat Membuat rahasia dasar dalam AWS Secrets Manager Panduan Pengguna.

    catatan

    Untuk membuat rahasia dalam konsol Secrets Manager, masukkan token Anda pada tab Plaintext ini. Jangan sertakan tanda kutip atau pemformatan lainnya. Dalam API, tentukan token sebagai nilai untuk properti SecretString ini.

  • Sebuah sumber daya rahasia dalam grup Greengrass yang mereferensikan rahasia Secrets Manager. Untuk informasi selengkapnya, lihat Men-deploy rahasia ke AWS IoT Greengrass core.

Parameter Konektor

Konektor ini menyediakan parameter berikut.

Version 5
TWILIO_ACCOUNT_SID

Akun Twilio SID yang digunakan untuk memanggil Twilio API.

Nama tampilanAWS IoTKonsol: Akun Twilio

Wajib: true

Jenis: string

Pola yang valid: .+

TwilioAuthTokenSecretArn

ARN rahasia Secrets Manager yang menyimpan token auth Twilio.

catatan

Ini digunakan untuk mengakses nilai rahasia lokal pada core.

Nama tampilanAWS IoTKonsol: ARN dari Twilio auth token rahasia

Wajib: true

Jenis: string

Pola yang valid: arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

TwilioAuthTokenSecretArn-ResourceId

ID dari sumber rahasia dalam grup Greengrass yang mereferensikan rahasia untuk token auth Twilio.

Nama tampilanAWS IoTKonsol: Sumber daya token autentikasi Twilio

Wajib: true

Jenis: string

Pola yang valid: .+

DefaultFromPhoneNumber

Nomor telepon Twilio diaktifkan default yang Twilio gunakan untuk mengirim pesan. Twilio menggunakan nomor ini untuk memulai teks atau panggilan.

  • Jika Anda tidak mengonfigurasi nomor telepon default, Anda harus menentukan nomor telepon dalam from_number properti dalam tubuh pesan input.

  • Jika Anda mengonfigurasi nomor telepon default, Anda dapat mengganti default secara opsional dengan menentukan from_number properti dalam tubuh pesan input.

Nama tampilanAWS IoTKonsol: Nomor telepon

Wajib: false

Jenis: string

Pola yang valid: ^$|\+[0-9]+

IsolationMode

Mode kontainerisasi untuk konektor ini. Default-nya adalah GreengrassContainer, yang berarti bahwa konektor berjalan dalam lingkungan waktu aktif terisolasi dalam kontainer AWS IoT Greengrass ini.

catatan

Pengaturan kontainerisasi default untuk grup tidak berlaku untuk konektor.

Nama tampilanAWS IoTKonsol: Mode isolasi kontainer

Wajib: false

Jenis: string

Nilai yang valid: GreengrassContainer or NoContainer

Pola yang valid: ^NoContainer$|^GreengrassContainer$

Version 1 - 4
TWILIO_ACCOUNT_SID

Akun Twilio SID yang digunakan untuk memanggil Twilio API.

Nama tampilanAWS IoTKonsol: Akun Twilio

Wajib: true

Jenis: string

Pola yang valid: .+

TwilioAuthTokenSecretArn

ARN rahasia Secrets Manager yang menyimpan token auth Twilio.

catatan

Ini digunakan untuk mengakses nilai rahasia lokal pada core.

Nama tampilanAWS IoTKonsol: ARN dari Twilio auth token rahasia

Wajib: true

Jenis: string

Pola yang valid: arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

TwilioAuthTokenSecretArn-ResourceId

ID dari sumber rahasia dalam grup Greengrass yang mereferensikan rahasia untuk token auth Twilio.

Nama tampilanAWS IoTKonsol: Sumber daya token autentikasi Twilio

Wajib: true

Jenis: string

Pola yang valid: .+

DefaultFromPhoneNumber

Nomor telepon Twilio diaktifkan default yang Twilio gunakan untuk mengirim pesan. Twilio menggunakan nomor ini untuk memulai teks atau panggilan.

  • Jika Anda tidak mengonfigurasi nomor telepon default, Anda harus menentukan nomor telepon dalam from_number properti dalam tubuh pesan input.

  • Jika Anda mengonfigurasi nomor telepon default, Anda dapat mengganti default secara opsional dengan menentukan from_number properti dalam tubuh pesan input.

Nama tampilanAWS IoTKonsol: Nomor telepon

Wajib: false

Jenis: string

Pola yang valid: ^$|\+[0-9]+

Buat Contoh Konektor (AWS CLI)

Contoh berikut perintah CLI membuat ConnectorDefinition dengan versi awal yang berisi konektor Notifikasi Twilio.

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
    "Connectors": [
        {
            "Id": "MyTwilioNotificationsConnector",
            "ConnectorArn": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/5",
            "Parameters": {
                "TWILIO_ACCOUNT_SID": "abcd12345xyz",
                "TwilioAuthTokenSecretArn": "arn:aws:secretsmanager:region:account-id:secret:greengrass-secret-hash",
                "TwilioAuthTokenSecretArn-ResourceId": "MyTwilioSecret",
                "DefaultFromPhoneNumber": "+19999999999",
                "IsolationMode" : "GreengrassContainer"
            }
        }
    ]
}'

Untuk tutorial yang menunjukkan cara menambahkan konektor Notifikasi Twilio ke grup, lihat Memulai dengan konektor Greengrass (CLI) dan Memulai dengan konektor Greengrass (konsol).

Data input

Konektor ini menerima informasi pesan Twilio pada dua topik MQTT. Pesan input harus dalam format JSON.

  • Informasi pesan teks pada twilio/txt topik.

  • Informasi pesan telepon dalam twilio/call topik.

catatan

Muatan pesan input dapat mencakup pesan teks (message) atau pesan suara (voice_message_location), tapi tidak keduanya.

Filter topik:twilio/txt
Properti pesan
request

Informasi tentang Notifikasi Twilio.

Wajib: true

Jenis: object yang mencakup properti berikut:

recipient

Penerima pesan. Hanya satu penerima yang didukung.

Wajib: true

Jenis: object yang mencakup properti berikut:

name

Nama penerima.

Wajib: true

Jenis: string

Pola yang valid: .*

phone_number

Nomor telepon penerima.

Wajib: true

Jenis: string

Pola yang valid: \+[1-9]+

message

Konten teks dari pesan teks. Hanya pesan teks yang didukung pada topik ini. Untuk pesan suara, gunakan twilio/call.

Wajib: true

Jenis: string

Pola yang valid: .+

from_number

Nomor telepon pengirim. Twilio menggunakan nomor telepon ini untuk memulai pesan. Properti ini diperlukan jika parameter DefaultFromPhoneNumber tidak dikonfigurasi. Jika DefaultFromPhoneNumber dikonfigurasi, Anda dapat menggunakan properti ini untuk menimpa default.

Wajib: false

Jenis: string

Pola yang valid: \+[1-9]+

retries

Nomor retries. Default-nya adalah 0.

Wajib: false

Jenis: integer

id

ID arbitrer untuk permintaan. Properti ini digunakan untuk memetakan permintaan input untuk respons output.

Wajib: true

Jenis: string

Pola yang valid: .+

Contoh input
{
    "request": {
        "recipient": {
            "name": "Darla",
            "phone_number": "+12345000000",
            "message": "Hello from the edge"
        },
        "from_number": "+19999999999",
        "retries": 3
    },
    "id": "request123"
}
Filter topik:twilio/call
Properti pesan
request

Informasi tentang Notifikasi Twilio.

Wajib: true

Jenis: object yang mencakup properti berikut:

recipient

Penerima pesan. Hanya satu penerima yang didukung.

Wajib: true

Jenis: object yang mencakup properti berikut:

name

Nama penerima.

Wajib: true

Jenis: string

Pola yang valid: .+

phone_number

Nomor telepon penerima.

Wajib: true

Jenis: string

Pola yang valid: \+[1-9]+

voice_message_location

URL konten audio untuk pesan suara. Ini harus dalam format TWIML. Hanya pesan suara yang didukung pada topik ini. Untuk pesan teks, gunakan twilio/txt.

Wajib: true

Jenis: string

Pola yang valid: .+

from_number

Nomor telepon pengirim. Twilio menggunakan nomor telepon ini untuk memulai pesan. Properti ini diperlukan jika parameter DefaultFromPhoneNumber tidak dikonfigurasi. Jika DefaultFromPhoneNumber dikonfigurasi, Anda dapat menggunakan properti ini untuk menimpa default.

Wajib: false

Jenis: string

Pola yang valid: \+[1-9]+

retries

Nomor retries. Default-nya adalah 0.

Wajib: false

Jenis: integer

id

ID arbitrer untuk permintaan. Properti ini digunakan untuk memetakan permintaan input untuk respons output.

Wajib: true

Jenis: string

Pola yang valid: .+

Contoh input
{
    "request": {
        "recipient": {
            "name": "Darla",
            "phone_number": "+12345000000",
            "voice_message_location": "https://some-public-TwiML"
        },
        "from_number": "+19999999999",
        "retries": 3
    },
    "id": "request123"
}

Data output

Konektor ini menerbitkan informasi status sebagai data output pada topik MQTT.

Filter topik dalam langganan

twilio/message/status

Contoh output: Sukses
{
    "response": {
        "status": "success",
        "payload": {
            "from_number": "+19999999999",
            "messages": {
                "message_status": "queued",
                "to_number": "+12345000000",
                "name": "Darla"
            }
        }
    },
    "id": "request123"
}
Contoh output: Gagal
{
    "response": {
        "status": "fail",
        "error_message": "Recipient name cannot be None",
        "error": "InvalidParameter",
        "payload": None
        }
    },
    "id": "request123"
}

Properti payload dalam output adalah respon dari Twilio API ketika pesan dikirim. Jika konektor mendeteksi bahwa data input tidak valid (sebagai contoh, itu tidak menentukan field input yang diperlukan), konektor mengembalikan kesalahan dan menetapkan nilai ke None. Berikut ini adalah contoh muatan:

{
    'from_number':'+19999999999',
    'messages': {
        'name':'Darla',
        'to_number':'+12345000000',
        'message_status':'undelivered'
    }
}
{
    'from_number':'+19999999999',
    'messages': {
        'name':'Darla',
        'to_number':'+12345000000',
        'message_status':'queued'
    }
}

Contoh Penggunaan

Gunakan langkah-langkah tingkat tinggi berikut untuk mengatur contoh fungsi Lambda Python 3.7 yang dapat Anda gunakan untuk mencoba konektor.

catatan

YangMemulai dengan konektor Greengrass (konsol)danMemulai dengan konektor Greengrass (CLI)Topik end-to-end langkah-langkah yang menunjukkan cara mengatur, dan menguji konektor Notifikasi Twilio

  1. Pastikan Anda memenuhi persyaratan untuk konektor.

  2. Buat dan terbitkan fungsi Lambda yang mengirimkan data input ke konektor.

    Simpan kode contoh sebagai file PY. Unduh dan unzip AWS IoT Greengrass Core SDK for Python. Kemudian, buat paket zip yang berisi file PY dan folder greengrasssdk dalam tingkat root. Paket zip ini adalah paket deployment yang Anda unggah ke AWS Lambda.

    Setelah Anda membuat fungsi Lambda Python 3.7, terbitkankan versi fungsi dan buat alias.

  3. Konfigurasikan grup Greengrass Anda.

    1. Tambahkan fungsi Lambda dengan aliasnya (direkomendasikan). Konfigurasikan siklus hidup Lambda sebagai berumur panjang (atau "Pinned": true dalam CLI).

    2. Tambahkan sumber daya rahasia yang diperlukan dan berikan akses baca ke fungsi Lambda.

    3. Tambahkan konektor dan konfigurasikan parameter.

    4. Tambahkan langganan yang mengizinkan konektor untuk menerima data input dan mengirim data output pada filter topik yang didukung.

      • Atur fungsi Lambda sebagai sumber, konektor sebagai target, dan gunakan filter topik input yang mendukung.

      • Atur konektor sebagai sumber, AWS IoT Core sebagai target, dan gunakan filter topik input yang mendukung. Anda menggunakan langganan ini untuk melihat pesan status dalam konsol AWS IoT tersebut.

  4. Men-deploy grup.

  5. Di konsol AWS IoT tersebut, pada halaman Tes ini, berlangganan ke topik data output untuk melihat pesan status dari konektor. Contoh fungsi Lambda yang berumur panjang dan mulai mengirim pesan segera setelah grup dalam-deploy.

    Setelah selesai pengujian, Anda dapat mengatur siklus hidup Lambda ke sesuai permintaan (atau "Pinned": false dalam CLI) dan men-deploy grup. Ini menghentikan fungsi dari mengirim pesan.

Contoh

Contoh fungsi Lambda berikut mengirimkan pesan input ke konektor. Contoh ini memicu pesan teks.

import greengrasssdk
import json

iot_client = greengrasssdk.client('iot-data')
TXT_INPUT_TOPIC = 'twilio/txt'
CALL_INPUT_TOPIC = 'twilio/call'

def publish_basic_message():

    txt = {
        "request": {
            "recipient" : {
                "name": "Darla",
                "phone_number": "+12345000000",
                "message": 'Hello from the edge'
            },
            "from_number" : "+19999999999"
        },
        "id" : "request123"
    }
    
    print("Message To Publish: ", txt)

    client.publish(topic=TXT_INPUT_TOPIC,
                   payload=json.dumps(txt))

publish_basic_message()

def lambda_handler(event, context):
    return

Lisensi

Konektor Notifikasi Twilio mencakup perangkat lunak/lisensi pihak ketiga berikut ini:

Konektor ini dirilis di bawah Perjanjian Lisensi Perangkat lunak core Greengrass.

Changelog

Tabel berikut menjelaskan perubahan dalam setiap versi konektor.

Versi

Perubahan

5

Ditambahkan parameter IsolationMode untuk mengonfigurasi mode kontainerisasi untuk konektor.

4

Memperbarui waktu aktif Lambda untuk Python 3.7, yang mengubah persyaratan waktu aktif.

3

Perbaiki untuk mengurangi pencatatan berlebihan.

2

Penyempurnaan dan perbaikan bug kecil.

1

Pelepasan .

Sebuah grup Greengrass dapat berisi hanya satu versi konektor pada suatu waktu. Untuk informasi lebih lanjut tentang pembaruan versi konektor, lihat Versi upgrade konektor.

Lihat juga