View a markdown version of this page

Verwenden Sie einen C2C (Cloud-to-Cloud) -Anschluss - Verwaltete Integrationen für AWS IoT Device Management

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Verwenden Sie einen C2C (Cloud-to-Cloud) -Anschluss

Ein C2C-Konnektor verwaltet die Übersetzung von Anfrage- und Antwortnachrichten und ermöglicht die Kommunikation zwischen verwalteten Integrationen und einer Cloud eines Drittanbieters. Er ermöglicht die einheitliche Steuerung verschiedener Gerätetypen, Plattformen und Protokolle, sodass Geräte von Drittanbietern integriert und verwaltet werden können.

Im folgenden Verfahren werden die Schritte zur Verwendung des C2C-Anschlusses aufgeführt.

Schritte zur Verwendung des C2C-Anschlusses:

  1. CreateCloudConnector

    Konfigurieren Sie einen Konnektor, um die bidirektionale Kommunikation zwischen Ihren verwalteten Integrationen und Clouds von Drittanbietern zu ermöglichen.

    Geben Sie bei der Einrichtung des Connectors die folgenden Details an:

    • Name: Wählen Sie einen aussagekräftigen Namen für den Connector.

    • Beschreibung: Geben Sie eine kurze Zusammenfassung des Zwecks und der Funktionen des Connectors an.

    • AWS Lambda ARN: Geben Sie den Amazon-Ressourcennamen (ARN) der AWS Lambda Funktion an, die den Connector mit Strom versorgt.

    Erstellen und implementieren Sie eine AWS Lambda Funktion, die mit APIs von Drittanbietern kommuniziert, um einen Connector zu erstellen. Rufen Sie als Nächstes die CreateCloudConnectorAPI in verwalteten Integrationen auf und stellen Sie die AWS Lambda Funktion ARN für die Registrierung bereit. Stellen Sie sicher, dass die AWS Lambda Funktion in demselben AWS Konto bereitgestellt wird, in dem Sie den Connector in verwalteten Integrationen erstellen. Ihnen wird eine eindeutige Connector-ID zugewiesen, um die Integration zu identifizieren.

    Beispiel für eine CreateCloudConnector API-Anfrage und -Antwort:

    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"
}

    Ablauf der Erstellung:

    Phase der Erstellung des Cloud-Connectors
    Anmerkung

    Verwenden Sie die ListCloudConnectorsAPIs GetCloudConnectorUpdateCloudConnectorDeleteCloudConnector,, und nach Bedarf für dieses Verfahren.

  2. CreateConnectorDestination

    Konfigurieren Sie Destinations so, dass sie die Einstellungen und Autorisierungsdaten bereitstellen, die Connectors benötigen, um sichere Verbindungen mit Clouds von Drittanbietern herzustellen. Verwenden Sie Destinations, um Ihre Autorisierungsdaten von Drittanbietern bei verwalteten Integrationen zu registrieren.

    Zwei Autorisierungstypen werden jetzt unterstützt:

    • OAuth 2.0 — Für Plattformen, die die OAuth-Autorisierung verwenden (Autorisierungs-URL, Token-URL, Client-Anmeldeinformationen)

    • GeneralAuthorization- Für Plattformen, die API-Schlüssel, Bearer-Token oder andere Nicht-OAuth-Autorisierungsmechanismen verwenden

    Voraussetzungen

    Bevor Sie eine ConnectorDestinationerstellen, müssen Sie:

    • Rufen Sie die CreateCloudConnectorAPI auf, um einen Connector zu erstellen. Die ID, die die Funktion zurückgibt, wird im CreateConnectorDestinationAPI-API-Aufruf verwendet.

    • Für die OAuth-Autorisierung:

      • Rufen Sie das tokenUrl für die Drittanbieterplattform ab (um einen AuthCode gegen ein AccessToken auszutauschen)

      • Rufen Sie das authUrl für die Drittanbieterplattform ab (für die Autorisierung durch den Endbenutzer)

      • Speichern Sie das clientId und clientSecret in AWS Secrets Manager

    • Für GeneralAuthorization:

      • Speichern Sie Ihre Autorisierungsmaterialien (API-Schlüssel, Inhaber-Token usw.) in AWS Secrets Manager

      • Jedes Autorisierungsmaterial benötigt einen Namen und eine Secrets Manager Manager-Referenz

    Beispiel für eine CreateConnectorDestination API-Anfrage (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"
}

    Beispiel für eine CreateConnectorDestination API-Anfrage ()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"
}

    Hauptunterschiede für GeneralAuthorization:

    • Kein AuthType Feld erforderlich

    • Kein SecretsManager Feld der obersten Ebene erforderlich

    • Verwendet ein Array AuthConfig.GeneralAuthorization.AuthMaterials

    • Jedes Authentifizierungsmaterial hat einen Namen und eine eigene Secrets Manager Manager-Referenz

    • Unterstützt mehrere Authentifizierungsmaterialien für future Anwendungsfälle

    Unterstützt derzeit ConnectorDestination auch OAuth und GeneralAuthorization Together in unserem. ConnectorDestination

    Ablauf bei der Erstellung von Cloud-Zielen:

    CreateConnectorDestination Phase des API-Aufrufs
    Anmerkung

    Verwenden Sie die ListConnectorDestinationsAPIs GetConnectorDestinationUpdateConnectorDestinationDeleteConnectorDestination,, und nach Bedarf für dieses Verfahren.

  3. CreateAccountAssociation

    Zuordnungen stellen die Beziehungen zwischen Cloud-Konten von Drittanbietern von Endbenutzern und einem Connector-Ziel dar. Nachdem Sie eine Zuordnung erstellt und Endbenutzer mit verwalteten Integrationen verknüpft haben, ist der Zugriff auf ihre Geräte über eine eindeutige Zuordnungs-ID möglich. Diese Integration ermöglicht drei Hauptfunktionen: das Erkennen von Geräten, das Senden von Befehlen und das Empfangen von Ereignissen.

    Voraussetzungen

    Bevor AccountAssociationSie eine erstellen, müssen Sie die folgenden Schritte ausführen:

    Beispiel für eine CreateAccountAssociation API-Anfrage (OAuth):

    Request:

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

{
    "Id":"string"
}

    Beispiel für eine CreateAccountAssociation API-Anfrage ()GeneralAuthorization:

    Request:

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

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

    Hauptunterschiede für GeneralAuthorization:

    • Beinhaltet GeneralAuthorization.AuthMaterialName ein Feld

    • Verweist auf eines der Authentifizierungsmaterialien, die in der definiert sind ConnectorDestination

    • Keine OAuth-Autorisierungs-URL in der Antwort

    Anmerkung

    Verwenden Sie die ListAccountAssociationsAPIs GetAccountAssociationUpdateAccountAssociation, DeleteAccountAssociation, und nach Bedarf für dieses Verfahren.

    An AccountAssociationhat einen Status, der von GetAccountAssociationund ListAccountAssociationsAPIs abgefragt wird. Diese APIs zeigen den Status der Assoziation an. Die StartAccountAssociationRefreshAPI ermöglicht die Aktualisierung eines AccountAssociationStatus, wenn sein Aktualisierungstoken abläuft.

  4. Erkennung von Geräten

    Jedes verwaltete Objekt ist mit gerätespezifischen Details wie der Seriennummer und einem Datenmodell verknüpft. Das Datenmodell beschreibt die Funktionalität des Geräts und gibt an, ob es sich um eine Glühbirne, einen Schalter, einen Thermostat oder einen anderen Gerätetyp handelt. Es gibt zwei Workflows für die Erkennung von Geräten von Drittanbietern und die Erstellung von ManagedThings: den herkömmlichen Discovery-Flow und den vorab integrierten Discovery-Flow.

    1. Option 1: Herkömmlicher Ablauf der Geräteerkennung

      Verwenden Sie diesen Workflow, wenn Sie die Geräte-IDs des Connectors nicht im Voraus kennen. Dieser Ablauf erkennt alle mit einem Konto verknüpften Geräte und ermöglicht es Ihnen, auszuwählen, welche Geräte integriert werden sollen.

      1. Rufen Sie die StartDeviceDiscoveryAPI auf, um den Geräteerkennungsprozess zu starten.

        Beispiel für eine StartDeviceDiscovery API-Anfrage und -Antwort:

        Request:

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

Response:

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

      2. Rufen Sie die GetDeviceDiscoveryAPI auf, um den Status des Erkennungsprozesses zu überprüfen.

      3. Rufen Sie die ListDiscoveredDevicesAPI auf, um die erkannten Geräte aufzulisten.

        Beispiel für eine ListDiscoveredDevices API-Anfrage und -Antwort:

        Request:

//Empty body

Response:

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

      4. Rufen Sie die CreateManagedThingAPI auf, um die Geräte aus der Discovery-Liste auszuwählen, die in verwaltete Integrationen importiert werden sollen.

        Beispiel für eine CreateManagedThing API-Anfrage und -Antwort:

        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. Rufen Sie die GetManagedThingAPI auf, um diese neu erstellte managedThing Datei anzuzeigen. Der Status wird sein. UNASSOCIATED

      6. Rufen Sie die RegisterAccountAssociationAPI auf, um dies einer bestimmten managedThing accountAssociation Person zuzuordnen. Am Ende einer erfolgreichen RegisterAccountAssociationAPI managedThing ändert sich der ACTIVATED Status.

        Beispiel für eine RegisterAccountAssociation API-Anfrage und -Antwort:

        Request:

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

Response:

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

    2. Option 2: Ablauf der Pre-onboarded Geräteerkennung

      Verwenden Sie diesen Workflow, wenn Sie die Geräte-IDs des Connectors bereits vor dem Onboarding kennen. Dieser Ablauf ist nützlich für vorab bereitgestellte Geräte oder wenn Sie bestimmte Geräte aus einem größeren Satz selektiv einbinden möchten. Dieser Ansatz reduziert die Anzahl der API-Aufrufe, die für die vollständige Registrierung und Aktivierung von Geräten erforderlich sind.

      Wichtig

      Um den vorab integrierten Cloud-Discovery-Flow verwenden zu können, müssen Sie die connectorDeviceId (Connector-Gerätekennung) kennen, bevor Sie den Onboarding-Prozess für das Gerät einleiten. Diese Kennung wird von der Plattform des Drittanbieters oder bei der Gerätebereitstellung abgerufen.

      1. Rufen Sie die CreateManagedThingAPI mit dem Materialtyp für die PRE_ONBOARDED_CLOUD Authentifizierung auf. Dadurch wird ein PRE_ASSOCIATED ManagedThing-Status mit mehreren Kontozuordnungen erstellt.

        Beispiel für eine CreateManagedThing API-Anfrage und -Antwort ()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" 
}
        Anmerkung

        Im AuthenticationMaterial Format für vorinstallierte Geräte können Sie eine oder mehrere Kontozuordnungs-IDs angeben. CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>:...

      2. (Optional) Rufen Sie die GetManagedThingAPI auf, um zu überprüfen, ob sich ManagedThing im Status befindet. PRE_ASSOCIATED

      3. Rufen Sie die StartDeviceDiscoveryAPI mit dem connectorDeviceIdList Parameter auf, um nur die vorinstallierten Geräte zu ermitteln.

        Beispiel für eine StartDeviceDiscovery API-Anfrage mit Konnektor: DeviceIdList

        Request:

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

Response:

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

        Bei Verwendung gibt der Erkennungsprozess nur Geräte zurückconnectorDeviceIdList, die den angegebenen Connector-Geräte-IDs entsprechen. Der Connector sendet ein DEVICE_DISCOVERY Ereignis SendConnectorEventmit den ermittelten Geräteinformationen.

      4. Nachdem die Erkennung erfolgreich abgeschlossen wurde, registriert Managed Integrations die vorinstallierten ManagedThings automatisch bei den zugehörigen Kontoverknüpfungen. Das ManagedThing wechselt vom Status zu. PRE_ASSOCIATED ACTIVATED

        Anmerkung

        Wenn die automatische Registrierung fehlschlägt und ManagedThing im DISCOVERED Status verbleibt, können Sie die RegisterAccountAssociationAPI manuell als Fallback aufrufen, um den Registrierungsprozess abzuschließen.

      5. (Optional) Rufen Sie die GetManagedThingAPI auf, um zu überprüfen, ob sich ManagedThing jetzt im Status befindet. ACTIVATED

  5. Senden Sie einen Befehl an das Gerät eines Drittanbieters

    Um ein neu integriertes Gerät zu steuern, verwenden Sie die SendManagedThingCommandAPI mit der zuvor erstellten Zuordnungs-ID und einer Steueraktion, die auf der vom Gerät unterstützten Funktion basiert. Der Connector verwendet gespeicherte Anmeldeinformationen aus dem Kontoverknüpfungsprozess, um sich bei der Drittanbieter-Cloud zu authentifizieren und den entsprechenden API-Aufruf für den Vorgang aufzurufen.

    Anmerkung

    Denn GeneralAuthorization der Konnektor ruft das Autorisierungsmaterial (API-Schlüssel, Bearer-Token usw.) von Secrets Manager unter Verwendung des in der angegebenen Autorisierungsmaterialnamens ab. AccountAssociation

    Beispiel für eine SendManagedThingCommand API-Anfrage und -Antwort:

    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"
}

    Befehl an den Gerätefluss eines Drittanbieters senden:

    Befehl an ein Gerät eines Drittanbieters senden

  6. Connector sendet Ereignisse an verwaltete Integrationen

    Die SendConnectorEventAPI erfasst vier Ereignistypen vom Connector bis hin zu verwalteten Integrationen, die durch die folgenden Aufzählungswerte für den Parameter Operation Type dargestellt werden:

    • DEVICE_COMMAND_RESPONSE: Die asynchrone Antwort, die der Connector als Antwort auf einen Befehl sendet.

    • DEVICE_DISCOVERY: Als Reaktion auf einen Geräteerkennungsprozess sendet der Connector die Liste der erkannten Geräte an verwaltete Integrationen und verwendet die API. SendConnectorEvent

    • DEVICE_EVENT: Sendet die empfangenen Geräteereignisse.

    • DEVICE_COMMAND_REQUEST: Vom Gerät initiierte Befehlsanfragen. Zum Beispiel WebRTC-Workflows.

    Der Connector kann mit einem optionalen userId Parameter auch Geräteereignisse mithilfe der SendConnectorEventAPI weiterleiten.

    Anmerkung

    Für GeneralAuthorization: Bei der Verwendung GeneralAuthorization muss die userId für jeden Secrets-ARN und jede Secrets-Version eindeutig sein.

    • Für Geräteereignisse mit einem: userId

      Beispiel für eine SendConnectorEvent API-Anfrage und -Antwort:

      Request:

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

Response:

{
    "ConnectorId": "string"
}

    • Für Geräteereignisse ohneuserId:

      Beispiel für eine SendConnectorEvent API-Anfrage und -Antwort:

      Request:

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

Response:

{
    "ConnectorId": "string"
}

    Verwenden Sie den Abmeldemechanismus, um die Verknüpfung zwischen einer bestimmten managedThing und einer Kontoverknüpfung zu entfernen:

    Beispiel für eine DeregisterAccountAssociation API-Anfrage und -Antwort:

    Request:

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

Response:

HTTP/1.1 200 // Empty body

    Ereignisablauf senden:

    Ablauf der Ereignisse senden

  7. Aktualisieren Sie den Connector-Status auf „Gelistet“, um ihn für andere Kunden mit verwalteten Integrationen sichtbar zu machen

    Standardmäßig sind Konnektoren privat und nur für das AWS Konto sichtbar, mit dem sie erstellt wurden. Sie können wählen, ob ein Connector für andere Kunden mit verwalteten Integrationen sichtbar sein soll.

    Um Ihren Connector mit anderen Benutzern zu teilen, verwenden Sie die Option Sichtbar machen AWS-Managementkonsole auf der Seite mit den Connector-Details, um Ihre Connector-ID AWS zur Überprüfung einzureichen. Nach der Genehmigung steht der Connector allen Benutzern verwalteter Integrationen in derselben AWS-Region Version zur Verfügung. Darüber hinaus können Sie den Zugriff auf bestimmte AWS Konto-IDs einschränken, indem Sie die Zugriffsrichtlinie für die dem Connector zugeordnete AWS Lambda Funktion ändern. Um sicherzustellen, dass Ihr Connector von anderen Kunden verwendet werden kann, verwalten Sie die IAM-Zugriffsberechtigungen für Ihre Lambda-Funktion von anderen AWS Konten auf Ihren sichtbaren Connector.

    Lesen Sie die AWS-Service Bedingungen und Richtlinien Ihrer Organisation, die die gemeinsame Nutzung von Connectoren und die Zugriffsberechtigungen regeln, bevor Sie Connectors für andere Kunden mit verwalteten Integrationen sichtbar machen.