View a markdown version of this page

Use um conector C2C () Cloud-to-Cloud - Integrações gerenciadas para AWS IoT Device Management

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Use um conector C2C () Cloud-to-Cloud

Um conector C2C gerencia a tradução de mensagens de solicitação e resposta e permite a comunicação entre integrações gerenciadas e uma nuvem de fornecedores terceirizados. Ele facilita o controle unificado em diferentes tipos de dispositivos, plataformas e protocolos, permitindo que dispositivos de terceiros sejam integrados e gerenciados.

O procedimento a seguir lista as etapas para usar o conector C2C.

Etapas para usar o conector C2C:

  1. CreateCloudConnector

    Configure um conector para permitir a comunicação bidirecional entre suas integrações gerenciadas e nuvens de fornecedores terceirizados.

    Ao configurar o conector, forneça os seguintes detalhes:

    • Nome: escolha um nome descritivo para o conector.

    • Descrição: Forneça um breve resumo da finalidade e das capacidades do conector.

    • AWS Lambda ARN: especifique o Amazon Resource Name (ARN) da AWS Lambda função que alimentará o conector.

    Crie e implante uma AWS Lambda função que se comunica com APIs de fornecedores terceirizados para criar um conector. Em seguida, chame a CreateCloudConnectorAPI nas integrações gerenciadas e forneça o ARN da AWS Lambda função para registro. Certifique-se de que a AWS Lambda função seja implantada na mesma AWS conta em que você criou o conector nas integrações gerenciadas. Você receberá um ID de conector exclusivo para identificar a integração.

    Exemplo de solicitação e resposta de 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"
}

    Fluxo de criação:

    Fase de criação do conector de nuvem
    nota

    Use as ListCloudConnectorsAPIs GetCloudConnectorUpdateCloudConnectorDeleteCloudConnector,, e conforme necessário para esse procedimento.

  2. CreateConnectorDestination

    Configure os destinos para fornecer as configurações e as credenciais de autorização que os conectores precisam para estabelecer conexões seguras com nuvens de fornecedores terceirizados. Use Destinations para registrar suas credenciais de autorização de terceiros com integrações gerenciadas.

    Agora há suporte para dois tipos de autorização:

    • OAuth 2.0 - Para plataformas que usam autorização OAuth (URL de autorização, URL do token, credenciais do cliente)

    • GeneralAuthorization- Para plataformas que usam chaves de API, tokens portadores ou qualquer mecanismo de autorização que não seja OAuth

    Pré-requisitos

    Antes de criar um ConnectorDestination, você deve:

    • Chame a CreateCloudConnectorAPI para criar um conector. O ID que a função retorna é usado na chamada CreateConnectorDestinationda API API.

    • Para autorização do OAuth:

      • Recupere o tokenUrl para a plataforma de terceiros (para trocar um AuthCode por um AccessToken)

      • Recupere o authUrl para a plataforma de terceiros (para autorização do usuário final)

      • Armazene o clientId e clientSecret em AWS Secrets Manager

    • Para GeneralAuthorization:

      • Armazene seus materiais de autorização (chaves de API, tokens de portador etc.) em AWS Secrets Manager

      • Cada material de autorização precisa de um nome e uma referência ao Secrets Manager.

    Exemplo de solicitação de 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"
}

    Exemplo de solicitação de 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"
}

    Principais diferenças para GeneralAuthorization:

    • Nenhum AuthType campo obrigatório

    • Nenhum SecretsManager campo de nível superior é necessário

    • Usa AuthConfig.GeneralAuthorization.AuthMaterials matriz

    • Cada material de autenticação tem um nome e sua própria referência ao Secrets Manager.

    • Suporta vários materiais de autenticação para futuros casos de uso

    Atualmente, ConnectorDestination também suporta OAuth e GeneralAuthorization junto em nosso. ConnectorDestination

    Fluxo de criação de destinos na nuvem:

    CreateConnectorDestination Fase de invocação da API
    nota

    Use as ListConnectorDestinationsAPIs GetConnectorDestinationUpdateConnectorDestinationDeleteConnectorDestination,, e conforme necessário para esse procedimento.

  3. CreateAccountAssociation

    As associações representam os relacionamentos entre as contas de nuvem de terceiros dos usuários finais e um destino de conector. Depois de criar uma associação e vincular os usuários finais às integrações gerenciadas, seus dispositivos podem ser acessados por meio de uma ID de associação exclusiva. Essa integração permite três funções principais: descobrir dispositivos, enviar comandos e receber eventos.

    Pré-requisitos

    Antes de criar um, AccountAssociationvocê deve concluir o seguinte:

    Exemplo de solicitação de CreateAccountAssociation API (OAuth):

    Request:

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

{
    "Id":"string"
}

    Exemplo de solicitação de 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"
}

    Principais diferenças para GeneralAuthorization:

    • Inclui GeneralAuthorization.AuthMaterialName campo

    • Faz referência a um dos materiais de autenticação definidos no ConnectorDestination

    • Nenhum URL de autorização do OAuth na resposta

    nota

    Use as ListAccountAssociationsAPIs GetAccountAssociationUpdateAccountAssociationDeleteAccountAssociation,, e conforme necessário para esse procedimento.

    An AccountAssociationtem um estado que é consultado a partir de GetAccountAssociationListAccountAssociationsAPIs. Essas APIs mostram o estado da Associação. A StartAccountAssociationRefreshAPI permite a atualização de um AccountAssociationestado quando seu token de atualização expira.

  4. Descoberta de dispositivos

    Cada item gerenciado está vinculado a detalhes específicos do dispositivo, como seu número de série e um modelo de dados. O modelo de dados descreve a funcionalidade do dispositivo, indicando se é uma lâmpada, interruptor, termostato ou outro tipo de dispositivo. Há dois fluxos de trabalho para descobrir dispositivos de terceiros e criar coisas gerenciadas: o fluxo de descoberta tradicional e o fluxo de descoberta pré-integrado.

    1. Opção 1: fluxo tradicional de descoberta de dispositivos

      Use esse fluxo de trabalho quando você não souber com antecedência os IDs do dispositivo conector. Esse fluxo descobre todos os dispositivos associados a uma conta e permite que você selecione quais dispositivos integrar.

      1. Chame a StartDeviceDiscoveryAPI para iniciar o processo de descoberta do dispositivo.

        Exemplo de solicitação e resposta de StartDeviceDiscovery API:

        Request:

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

Response:

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

      2. Invoque a GetDeviceDiscoveryAPI para verificar o status do processo de descoberta.

      3. Invoque a ListDiscoveredDevicesAPI para listar os dispositivos descobertos.

        Exemplo de solicitação e resposta de 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. Invoque a CreateManagedThingAPI para selecionar os dispositivos da lista de descoberta a serem importados para integrações gerenciadas.

        Exemplo de solicitação e resposta de 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. Invoque a GetManagedThingAPI para ver isso recém-criadomanagedThing. O status seráUNASSOCIATED.

      6. Invoque a RegisterAccountAssociationAPI para associá-la managedThing a um específicoaccountAssociation. No final de uma RegisterAccountAssociationAPI bem-sucedida, o ACTIVATED estado managedThing muda.

        Exemplo de solicitação e resposta de RegisterAccountAssociation API:

        Request:

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

Response:

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

    2. Opção 2: fluxo de descoberta de Pre-onboarded dispositivos

      Use esse fluxo de trabalho quando você já conhece os IDs do dispositivo conector antes da integração. Esse fluxo é útil para dispositivos pré-provisionados ou quando você deseja integrar seletivamente dispositivos específicos de um conjunto maior. Essa abordagem reduz o número de chamadas de API necessárias para registrar e ativar totalmente os dispositivos.

      Importante

      Para usar o fluxo de descoberta de nuvem pré-integrado, você deve conhecer o connectorDeviceId (identificador do dispositivo conector) antes de iniciar o processo de integração do dispositivo. Esse identificador é obtido da plataforma do fornecedor terceirizado ou durante o provisionamento do dispositivo.

      1. Invoque a CreateManagedThingAPI com o tipo PRE_ONBOARDED_CLOUD de material de autenticação. Isso cria um ManagedThing no PRE_ASSOCIATED estado com várias associações de contas.

        Exemplo de solicitação e resposta de 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" 
}
        nota

        O AuthenticationMaterial formato para dispositivos pré-integrados é CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>:... onde você pode especificar uma ou mais IDs de associação de conta.

      2. (Opcional) Invoque a GetManagedThingAPI para verificar se o ManagedThing está no estado. PRE_ASSOCIATED

      3. Chame a StartDeviceDiscoveryAPI com o connectorDeviceIdList parâmetro para descobrir somente os dispositivos pré-integrados.

        Exemplo de solicitação de StartDeviceDiscovery API com conectorDeviceIdList:

        Request:

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

Response:

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

        Ao usarconnectorDeviceIdList, o processo de descoberta retorna somente dispositivos que correspondam às IDs de dispositivo conector especificadas. O conector enviará um DEVICE_DISCOVERY evento via SendConnectorEventcom as informações do dispositivo descoberto.

      4. Após a conclusão bem-sucedida da descoberta, as integrações gerenciadas registram automaticamente os ManagedThings pré-integrados nas associações de contas associadas. O ManagedThing faz a transição de PRE_ASSOCIATED para estado. ACTIVATED

        nota

        Se o registro automático falhar e o ManagedThing permanecer no DISCOVERED estado, você poderá invocar manualmente a RegisterAccountAssociationAPI como alternativa para concluir o processo de registro.

      5. (Opcional) Invoque a GetManagedThingAPI para verificar se o ManagedThing está agora no estado. ACTIVATED

  5. Envie um comando para o dispositivo de terceiros

    Para controlar um dispositivo recém-integrado, use a SendManagedThingCommandAPI, com o ID de associação criado anteriormente e uma ação de controle com base na capacidade suportada pelo dispositivo. O conector usa credenciais armazenadas do processo de vinculação de contas para se autenticar na nuvem de terceiros e invocar a chamada de API relevante para a operação.

    nota

    Pois GeneralAuthorization, o conector recupera o material de autorização (chave de API, token do portador etc.) do Secrets Manager usando o nome do material de autorização especificado no. AccountAssociation

    Exemplo de solicitação e resposta de 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"
}

    Envie o comando para o fluxo de dispositivos de terceiros:

    Enviar comando para dispositivo de terceiros

  6. O conector envia eventos para integrações gerenciadas

    A SendConnectorEventAPI captura quatro tipos de eventos, do conector às integrações gerenciadas, representados pelos seguintes valores de enumeração para o parâmetro Operation Type:

    • DEVICE_COMMAND_RESPONSE: a resposta assíncrona que o conector envia em resposta a um comando.

    • DEVICE_DISCOVERY: em resposta a um processo de descoberta de dispositivos, o conector envia a lista de dispositivos descobertos para integrações gerenciadas e usa a API. SendConnectorEvent

    • DEVICE_EVENT: envia os eventos recebidos do dispositivo.

    • DEVICE_COMMAND_REQUEST: solicitações de comando iniciadas a partir do dispositivo. Por exemplo, fluxos de trabalho do WebRTC.

    O conector também pode encaminhar eventos do dispositivo usando a SendConnectorEventAPI, com um userId parâmetro opcional.

    nota

    Para GeneralAuthorization: Ao usar GeneralAuthorization, para cada ARN e versão do Secrets, o ID do usuário precisa ser exclusivo.

    • Para eventos de dispositivos comuserId:

      Exemplo de solicitação e resposta de SendConnectorEvent API:

      Request:

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

Response:

{
    "ConnectorId": "string"
}

    • Para eventos de dispositivos semuserId:

      Exemplo de solicitação e resposta de SendConnectorEvent API:

      Request:

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

Response:

{
    "ConnectorId": "string"
}

    Para remover o vínculo entre uma associação específica managedThing e uma conta, use o mecanismo de cancelamento de registro:

    Exemplo de solicitação e resposta de DeregisterAccountAssociation API:

    Request:

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

Response:

HTTP/1.1 200 // Empty body

    Enviar fluxo de eventos:

    Enviar fluxo de eventos

  7. Atualize o status do conector para “Listado” para torná-lo visível para outros clientes de integrações gerenciadas

    Por padrão, os conectores são privados e visíveis somente para a AWS conta que os criou. Você pode optar por tornar um conector visível para outros clientes de integrações gerenciadas.

    Para compartilhar seu conector com outros usuários, use a opção Tornar visível Console de gerenciamento da AWS na página de detalhes do conector para enviar seu ID de conector AWS para análise. Depois de aprovado, o conector fica disponível para todos os usuários de integrações gerenciadas no mesmo Região da AWS. Além disso, você pode restringir o acesso a IDs de AWS conta específicos modificando a política de acesso na AWS Lambda função associada ao conector. Para garantir que seu conector possa ser usado por outros clientes, gerencie as permissões de acesso do IAM em sua função Lambda de AWS outras contas para seu conector visível.

    Analise os AWS service (Serviço da AWS) termos e as políticas da sua organização que regem o compartilhamento de conectores e as permissões de acesso antes de tornar os conectores visíveis para outros clientes de integrações gerenciadas.