View a markdown version of this page

Gunakan konektor C2C () Cloud-to-Cloud - Integrasi Terkelola untuk AWS IoT Device Management

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

Gunakan konektor C2C () Cloud-to-Cloud

Konektor C2C mengelola terjemahan pesan permintaan dan respons, dan memungkinkan komunikasi antara integrasi terkelola dan cloud vendor pihak ketiga. Ini memfasilitasi kontrol terpadu di berbagai jenis perangkat, platform, dan protokol yang memungkinkan perangkat pihak ketiga untuk di-onboard dan dikelola.

Prosedur berikut mencantumkan langkah-langkah untuk menggunakan konektor C2C.

Langkah-langkah untuk menggunakan konektor C2C:

  1. CreateCloudConnector

    Konfigurasikan konektor untuk mengaktifkan komunikasi dua arah antara integrasi terkelola Anda dan cloud vendor pihak ketiga.

    Saat mengatur konektor, berikan detail berikut:

    • Nama: Pilih nama deskriptif untuk konektor.

    • Deskripsi: Berikan ringkasan singkat tentang tujuan dan kemampuan konektor.

    • AWS Lambda ARN: Tentukan Nama Sumber Daya Amazon (ARN) dari AWS Lambda fungsi yang akan memberi daya pada konektor.

    Buat dan terapkan AWS Lambda fungsi yang berkomunikasi dengan API vendor pihak ketiga untuk membuat konektor. Selanjutnya, panggil CreateCloudConnectorAPI dalam integrasi terkelola, dan berikan AWS Lambda fungsi ARN untuk pendaftaran. Pastikan bahwa AWS Lambda fungsi tersebut diterapkan di AWS akun yang sama tempat Anda memasang konektor dalam integrasi terkelola. Anda akan diberi ID Konektor unik untuk mengidentifikasi integrasi.

    Contoh Permintaan dan Respons CreateCloudConnector API:

    Request:

{
    "Name": "CreateCloudConnector",
    "Description": "Testing for C2C",
    "EndpointType": "LAMBDA",
    "EndpointConfig": {
        "lambda": {
            "arn": "arn:aws:lambda:us-east-1:xxxxxx:function:TestingConnector"
        }
    },
    "ClientToken": "abc"
}

Response:

{
    "Id": "string"
}

    Aliran penciptaan:

    Fase pembuatan konektor cloud
    catatan

    Gunakan GetCloudConnector,, UpdateCloudConnectorDeleteCloudConnector, dan ListCloudConnectorsAPI sesuai kebutuhan untuk prosedur ini.

  2. CreateConnectorDestination

    Konfigurasikan Destinasi untuk menyediakan pengaturan dan kredensional otorisasi yang diperlukan konektor untuk membuat koneksi aman dengan cloud vendor pihak ketiga. Gunakan Destinasi untuk mendaftarkan kredensil otorisasi pihak ketiga Anda dengan integrasi terkelola.

    Dua jenis otorisasi sekarang didukung:

    • OAuth 2.0 - Untuk platform yang menggunakan otorisasi OAuth (URL otorisasi, URL token, kredensi klien)

    • GeneralAuthorization- Untuk platform yang menggunakan kunci API, token pembawa, atau mekanisme otorisasi non-OAuth

    Prasyarat

    Sebelum membuat ConnectorDestination, Anda harus:

    • Panggil CreateCloudConnectorAPI untuk membuat konektor. ID yang dikembalikan fungsi digunakan dalam panggilan CreateConnectorDestinationAPI API.

    • Untuk otorisasi OAuth:

      • Ambil platform pihak ketiga (tokenUrluntuk menukar AuthCode dengan AccessToken)

      • Ambil authUrl untuk platform pihak ketiga (untuk otorisasi pengguna akhir)

      • Simpan clientId dan clientSecret di AWS Secrets Manager

    • Untuk GeneralAuthorization:

      • Simpan materi otorisasi Anda (kunci API, token pembawa, dll.) AWS Secrets Manager

      • Setiap materi otorisasi membutuhkan nama dan referensi Secrets Manager

    Contoh Permintaan CreateConnectorDestination API (OAuth):

    Request:

{
    "Name": "CreateConnectorDestination",
    "Description": "CreateConnectorDestination",
    "AuthType": "OAUTH",
    "AuthConfig": {
        "oAuth": {
            "authUrl": "https://xxxx.com/oauth2/authorize",
            "tokenUrl": "https://xxxx/oauth2/token",
            "scope": "testScope",
            "tokenEndpointAuthenticationScheme": "HTTP_BASIC",
            "oAuthCompleteRedirectUrl": "about:blank",
            "proactiveRefreshTokenRenewal": {
                "enabled": false,
                "DaysBeforeRenewal": 30
            }
        }
    },
    "CloudConnectorId": "<connectorId>",
    "SecretsManager": {
        "arn": "arn:aws:secretsmanager:*****:secret:*******",
        "versionId": "********"
    },
    "ClientToken": "***"
}

Response:

{
    "Id":"string"
}

    Contoh Permintaan CreateConnectorDestination API (GeneralAuthorization):

    Request:

{
    "Name": "CreateConnectorDestination",
    "Description": "GeneralAuthorization test destination",
    "AuthConfig": {
        "GeneralAuthorization": {
            "AuthMaterials": [
                {
                    "AuthMaterialName": "AuthKey1",
                    "SecretsManager": {
                        "arn": "arn:aws:secretsmanager:*****:secret:*******",
                        "versionId": "********"
                    }
                }
            ]
        }
    },
    "CloudConnectorId": "<connectorId>",
    "ClientToken": "***"
}

Response:

{
    "Id": "string"
}

    Perbedaan utama untuk GeneralAuthorization:

    • Tidak ada AuthType bidang yang diperlukan

    • Tidak diperlukan SecretsManager bidang tingkat atas

    • Menggunakan AuthConfig.GeneralAuthorization.AuthMaterials array

    • Setiap materi autentikasi memiliki nama dan referensi Secrets Manager sendiri

    • Mendukung beberapa materi otentikasi untuk kasus penggunaan di masa mendatang

    Saat ini, ConnectorDestination juga mendukung OAuth dan GeneralAuthorization bersama-sama di kami. ConnectorDestination

    Alur pembuatan tujuan cloud:

    CreateConnectorDestination Fase pemanggilan API
    catatan

    Gunakan GetConnectorDestination,, UpdateConnectorDestinationDeleteConnectorDestination, dan ListConnectorDestinationsAPI sesuai kebutuhan untuk prosedur ini.

  3. CreateAccountAssociation

    Asosiasi mewakili hubungan antara akun cloud pihak ketiga pengguna akhir dan tujuan konektor. Setelah membuat Asosiasi dan menautkan pengguna akhir ke integrasi terkelola, perangkat mereka dapat diakses melalui ID Asosiasi yang unik. Integrasi ini memungkinkan tiga fungsi utama: menemukan perangkat, mengirim perintah, dan menerima acara.

    Prasyarat

    Sebelum membuat, AccountAssociationAnda harus menyelesaikan yang berikut:

    Contoh Permintaan CreateAccountAssociation API (OAuth):

    Request:

{
    "Name": "CreateAccountAssociation",
    "Description": "CreateAccountAssociation",
    "ConnectorDestinationId": "<destinationId>",
    "ClientToken": "***"
}
        
Response:

{
    "Id":"string"
}

    Contoh Permintaan CreateAccountAssociation API (GeneralAuthorization):

    Request:

{
    "Name": "CreateAccountAssociation",
    "Description": "GeneralAuthorization test account association",
    "GeneralAuthorization": {
        "AuthMaterialName": "AuthKey1"
    },
    "ConnectorDestinationId": "<destinationId>",
    "ClientToken": "***"
}
        
Response:

{
    "AccountAssociationId": "string",
    "Arn": "string",
    "AssociationState": "ASSOCIATION_SUCCEEDED"
}

    Perbedaan utama untuk GeneralAuthorization:

    • Termasuk GeneralAuthorization.AuthMaterialName bidang

    • Referensi salah satu bahan autentikasi yang didefinisikan dalam ConnectorDestination

    • Tidak ada URL otorisasi OAuth dalam tanggapan

    catatan

    Gunakan GetAccountAssociation,, UpdateAccountAssociationDeleteAccountAssociation, dan ListAccountAssociationsAPI sesuai kebutuhan untuk prosedur ini.

    An AccountAssociationmemiliki status yang ditanyakan dari GetAccountAssociationdan ListAccountAssociationsAPI. API ini menunjukkan status Asosiasi. StartAccountAssociationRefreshAPI memungkinkan penyegaran AccountAssociationstatus saat token penyegarannya kedaluwarsa.

  4. Penemuan perangkat

    Setiap hal yang dikelola terkait dengan detail khusus perangkat, seperti nomor seri dan model data. Model data menjelaskan fungsionalitas perangkat, menunjukkan apakah itu bola lampu, sakelar, termostat, atau jenis perangkat lain. Ada dua alur kerja untuk menemukan perangkat pihak ketiga dan membuat ManagedThings: alur penemuan tradisional dan alur penemuan pra-onboard.

    1. Opsi 1: Aliran Penemuan Perangkat Tradisional

      Gunakan alur kerja ini jika Anda tidak mengetahui ID perangkat konektor sebelumnya. Alur ini menemukan semua perangkat yang terkait dengan akun dan memungkinkan Anda memilih perangkat mana yang akan dionboard.

      1. Panggil StartDeviceDiscoveryAPI untuk memulai proses penemuan perangkat.

        Contoh Permintaan dan Respons StartDeviceDiscovery API:

        Request:

{
    "DiscoveryType": "CLOUD",
    "AccountAssociationId": "*****",
    "ClientToken": "abc"
}

Response:

{
    "Id": "string",
    "StartedAt": number
}

      2. Memanggil GetDeviceDiscoveryAPI untuk memeriksa status proses penemuan.

      3. Panggil ListDiscoveredDevicesAPI untuk membuat daftar perangkat yang ditemukan.

        Contoh Permintaan dan Respons ListDiscoveredDevices API:

        Request:

//Empty body

Response:

{
    "Items": [
    {
      "Brand": "string",
      "ConnectorDeviceId": "string",
      "ConnectorDeviceName": "string",
      "DeviceTypes": [ "string" ],
      "DiscoveredAt": number,
      "ManagedThingId": "string",
      "Model": "string",
      "Modification": "string"
    }
],
    "NextToken": "string"
}

      4. Memanggil CreateManagedThingAPI untuk memilih perangkat dari daftar penemuan yang akan diimpor ke integrasi terkelola.

        Contoh Permintaan dan Respons CreateManagedThing API:

        Request:
              
{
    "Role": "DEVICE",
    "AuthenticationMaterial": "CLOUD:<deviceDiscoveryId>:<connectorDeviceId>",
    "AuthenticationMaterialType": "DISCOVERED_DEVICE",
    "Name": "sample-device-name",
    "ClientToken": "xxx"
}

Response:

{
   "Arn": "string", // This is the ARN of the managedThing
   "CreatedAt": number,
   "Id": "string" 
}

      5. Panggil GetManagedThingAPI untuk melihat ini yang baru dibuatmanagedThing. Statusnya akanUNASSOCIATED.

      6. Panggil RegisterAccountAssociationAPI untuk mengaitkan ini managedThing dengan yang spesifikaccountAssociation. Di akhir RegisterAccountAssociationAPI yang berhasil, managedThing perubahan ACTIVATED status.

        Contoh Permintaan dan Respons RegisterAccountAssociation API:

        Request:

{
    "AccountAssociationId": "string",
    "DeviceDiscoveryId": "string",
    "ManagedThingId": "string"
}

Response:

{
    "AccountAssociationId": "string",
    "DeviceDiscoveryId": "string",
    "ManagedThingId": "string"
}

    2. Opsi 2: Aliran Penemuan Pre-onboarded Perangkat

      Gunakan alur kerja ini saat Anda sudah mengetahui ID perangkat konektor sebelum melakukan onboarding. Alur ini berguna untuk perangkat yang telah disediakan sebelumnya atau saat Anda ingin secara selektif melakukan onboard perangkat tertentu dari set yang lebih besar. Pendekatan ini mengurangi jumlah panggilan API yang diperlukan untuk sepenuhnya mendaftar dan mengaktifkan perangkat.

      penting

      Untuk menggunakan alur penemuan cloud pra-onboard, Anda harus mengetahui connectorDeviceId (pengenal perangkat konektor) sebelum memulai proses orientasi perangkat. Pengenal ini diperoleh dari platform vendor pihak ketiga atau selama penyediaan perangkat.

      1. Memanggil CreateManagedThingAPI dengan jenis bahan PRE_ONBOARDED_CLOUD otentikasi. Ini membuat ManagedThing dalam PRE_ASSOCIATED keadaan dengan beberapa asosiasi akun.

        Contoh Permintaan dan Respons CreateManagedThing API (Pre-onboarded):

        Request:
              
{
    "Role": "DEVICE",
    "AuthenticationMaterial": "CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>",
    "AuthenticationMaterialType": "PRE_ONBOARDED_CLOUD",
    "Name": "pre-onboarded-device-name",
    "ClientToken": "xxx"
}

Response:

{
   "Arn": "string", // This is the ARN of the managedThing
   "CreatedAt": number,
   "Id": "string" 
}
        catatan

        AuthenticationMaterialFormat untuk perangkat pra-onboard adalah CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>:... tempat Anda dapat menentukan satu atau beberapa ID asosiasi akun.

      2. (Opsional) Panggil GetManagedThingAPI untuk memverifikasi ManagedThing dalam status. PRE_ASSOCIATED

      3. Panggil StartDeviceDiscoveryAPI dengan connectorDeviceIdList parameter untuk menemukan hanya perangkat pra-onboard.

        Contoh Permintaan StartDeviceDiscovery API dengan konektorDeviceIdList:

        Request:

{
    "DiscoveryType": "CLOUD",
    "AccountAssociationId": "*****",
    "ConnectorDeviceIdList": [
        "connector-device-id-1",
        "connector-device-id-2",
        "connector-device-id-3"
    ],
    "ClientToken": "abc"
}

Response:

{
    "Id": "string",
    "StartedAt": number
}

        Saat menggunakanconnectorDeviceIdList, proses penemuan hanya mengembalikan perangkat yang cocok dengan ID perangkat konektor yang ditentukan. Konektor akan mengirim DEVICE_DISCOVERY acara melalui SendConnectorEventinformasi perangkat yang ditemukan.

      4. Setelah penemuan berhasil diselesaikan, integrasi terkelola secara otomatis mendaftarkan ManagedThings yang telah di-onboard ke asosiasi akun terkait mereka. Transisi ManagedThing dari PRE_ASSOCIATED ke negara bagian. ACTIVATED

        catatan

        Jika registrasi otomatis gagal dan ManagedThing tetap dalam DISCOVERED status, Anda dapat memanggil RegisterAccountAssociationAPI secara manual sebagai fallback untuk menyelesaikan proses pendaftaran.

      5. (Opsional) Panggil GetManagedThingAPI untuk memverifikasi ManagedThing sekarang dalam status. ACTIVATED

  5. Kirim perintah ke perangkat pihak ketiga

    Untuk mengontrol perangkat yang baru di-onboard, gunakan SendManagedThingCommandAPI, dengan ID Asosiasi yang dibuat sebelumnya dan tindakan kontrol berdasarkan kemampuan yang didukung oleh perangkat. Konektor menggunakan kredensil tersimpan dari proses penautan akun untuk mengautentikasi dengan cloud pihak ketiga dan memanggil panggilan API yang relevan untuk operasi tersebut.

    catatan

    Untuk GeneralAuthorization, konektor mengambil materi otorisasi (kunci API, token pembawa, dll.) dari Secrets Manager menggunakan nama materi otorisasi yang ditentukan dalam file. AccountAssociation

    Contoh Permintaan dan Respons SendManagedThingCommand API:

    Request:

{
    "AccountAssociationId": "string",
    "ConnectorAssociationId": "string",
    "Endpoints": [ 
       { 
          "capabilities": [ 
             { 
                "actions": [ 
                   { 
                      "actionTraceId": "string",
                      "name": "string",
                      "parameters": JSON value,
                      "ref": "string"
                   }
                ],
                "id": "string",
                "name": "string",
                "version": "string"
             }
          ],
          "endpointId": "string"
       }
    ]
}
        
Response:
        
{
   "TraceId": "string"
}

    Kirim perintah ke aliran perangkat pihak ketiga:

    Kirim perintah ke perangkat pihak ketiga

  6. Konektor mengirimkan acara ke integrasi terkelola

    SendConnectorEventAPI menangkap empat jenis peristiwa dari konektor ke integrasi terkelola, yang diwakili oleh nilai enum berikut untuk parameter Jenis Operasi:

    • DEVICE_COMMAND_RESPONSE: Respons asinkron yang dikirim konektor sebagai respons terhadap perintah.

    • DEVICE_DISCOVERY: Menanggapi proses penemuan perangkat, konektor mengirimkan daftar perangkat yang ditemukan ke integrasi terkelola, ia menggunakan API. SendConnectorEvent

    • DEVICE_EVENT: Mengirim peristiwa perangkat yang diterima.

    • DEVICE_COMMAND_REQUEST: Permintaan perintah dimulai dari perangkat. Misalnya, alur kerja WebRTC.

    Konektor juga dapat meneruskan peristiwa perangkat menggunakan SendConnectorEventAPI, dengan userId parameter opsional.

    catatan

    Untuk GeneralAuthorization: Saat menggunakan GeneralAuthorization, untuk setiap Rahasia ARN dan versi, userID harus unik.

    • Untuk acara perangkat denganuserId:

      Contoh Permintaan dan Respons SendConnectorEvent API:

      Request:

{
    "UserId": "*****",
    "Operation": "DEVICE_EVENT",
    "OperationVersion": "1.0",
    "StatusCode": 200,
    "ConnectorId": "****",
    "ConnectorDeviceId": "***",
    "TraceId": "***",
    "MatterEndpoint": {
        "id": "**",
        "clusters": [{
            .....
            }
        }]
    }
}

Response:

{
    "ConnectorId": "string"
}

    • Untuk acara perangkat tanpauserId:

      Contoh Permintaan dan Respons SendConnectorEvent API:

      Request:

{
    "Operation": "DEVICE_EVENT",
    "OperationVersion": "1.0",
    "StatusCode": 200,
    "ConnectorId": "*****",
    "ConnectorDeviceId": "****",
    "TraceId": "****",
    "MatterEndpoint": {
        "id": "**",
        "clusters": [{
            ....
        }]
    }
}

Response:

{
    "ConnectorId": "string"
}

    Untuk menghapus tautan antara asosiasi tertentu managedThing dan akun, gunakan mekanisme deregister:

    Contoh Permintaan dan Respons DeregisterAccountAssociation API:

    Request:

{
    "AccountAssociationId": "****",
    "ManagedThingId": "****"
}

Response:

HTTP/1.1 200 // Empty body

    Kirim alur acara:

    Kirim alur acara

  7. Perbarui status konektor ke “Terdaftar” agar terlihat oleh pelanggan integrasi terkelola lainnya

    Secara default, konektor bersifat pribadi dan hanya terlihat oleh AWS akun yang membuatnya. Anda dapat memilih untuk membuat konektor terlihat oleh pelanggan integrasi terkelola lainnya.

    Untuk membagikan konektor Anda dengan pengguna lain, gunakan opsi Buat terlihat Konsol Manajemen AWS di halaman detail konektor untuk mengirimkan ID konektor Anda AWS untuk ditinjau. Setelah disetujui, konektor tersedia untuk semua pengguna integrasi terkelola dalam hal yang sama Wilayah AWS. Selain itu, Anda dapat membatasi akses ke ID AWS akun tertentu dengan mengubah kebijakan akses pada fungsi terkait AWS Lambda konektor. Untuk memastikan konektor Anda dapat digunakan oleh pelanggan lain, kelola izin akses IAM pada fungsi Lambda Anda dari AWS akun lain ke konektor yang terlihat.

    Tinjau Layanan AWS persyaratan dan kebijakan organisasi Anda yang mengatur berbagi konektor dan izin akses sebelum membuat konektor terlihat oleh pelanggan integrasi terkelola lainnya.