Implementieren Sie Operationen an der C2C-Anschlussschnittstelle

Managed Integrations for AWS IoT Device Management definiert vier Vorgänge, die Sie ausführen AWS Lambda müssen, um sich als Konnektor zu qualifizieren. Ihr C2C-Konnektor muss jeden der folgenden Vorgänge implementieren:

1. AWS.ActivateUser- Verwaltete Integrationen für AWS IoT Device Management Dienste rufen diese API auf, um eine weltweit eindeutige Benutzerkennung abzurufen, die dem bereitgestellten OAuth2 0.0-Token zugeordnet ist. Dieser Vorgang kann optional verwendet werden, um zusätzliche Anforderungen für den Kontoverknüpfungsprozess zu erfüllen.

2. AWS.DiscoverDevices- verwaltete Integrationen für den AWS IoT Device Management Service rufen diese API an Ihren Connector auf, um Benutzergeräte zu erkennen

3. AWS.SendCommand- verwaltete Integrationen für den AWS IoT Device Management Service rufen diese API an Ihren Connector auf, um Befehle für Benutzergeräte zu senden

4. AWS.DeactivateUser- Managed Integrations for AWS IoT Device Management Service ruft diese API an Ihren Connector auf, um das Zugriffstoken des Benutzers zu deaktivieren, um die Verbindung zu Ihrem Autorisierungsserver zu trennen.

Managed Integrations for ruft AWS IoT Device Management während der Aktion immer die Lambda-Funktion mit einer JSON-Zeichenfolgennutzlast auf. AWS Lambda invokeFunction Anforderungsoperationen müssen in jeder Anforderungsnutzlast ein operationName Feld enthalten. Weitere Informationen finden Sie unter Invoke in der AWS Lambda API-Referenz.

Jeder Aufruf-Timeout ist auf zwei Sekunden festgelegt. Schlägt der Aufruf fehl, wird er fünfmal wiederholt.

Das Lambda, das Sie für Ihren Connector implementieren, analysiert eine operationName aus der Payload der Anfrage und implementiert die entsprechende Funktionalität für die Zuordnung zur Drittanbieter-Cloud:

public ConnectorResponse handleRequest(final ConnectorRequest request) 
        throws OperationFailedException {
    Operation operation;
    try {
        operation = Operation.valueOf(request.payload().operationName());
    } catch (IllegalArgumentException ex) {
        throw new ValidationException(
           "Unknown operation '%s'".formatted(request.payload().operationName()), 
           ex
        );
    }

    return switch (operation) {
        case ActivateUser -> activateUserManager.activateUser(request);
        case DiscoverDevices -> deviceDiscoveryManager.listDevices(request);
        case SendCommand -> sendCommandManager.sendCommand(request);
        case DeactivateUser -> deactivateUser.deactivateUser(request);
    };
}

Anmerkung

Der Entwickler des Connectors muss die im vorherigen activateUserManager.activateUser(request) Beispiel aufgeführten deactivateUser.deactivateUser Operationen deviceDiscoveryManager.listDevices(request)sendCommandManager.sendCommand(request),, und implementieren.

Das folgende Beispiel beschreibt eine generische Konnektoranfrage von verwalteten Integrationen, in der gemeinsame Felder für alle erforderlichen Schnittstellen vorhanden sind. Aus dem Beispiel können Sie ersehen, dass es sowohl einen Anforderungsheader als auch eine Anforderungs-Payload gibt. Anforderungsheader sind auf jeder Bedienoberfläche üblich.

{
 	"header": {
 		"auth": { 
 			"token": “ashriu32yr97feqy7afsaf”, 
 			"type": “OAuth2.0"
 		}
 	},
 	"payload":{
 		"operationName": "AWS.SendCommand",
 		"operationVersion": "1.0",
 		"connectorId": “exampleId”,
 	…
 	}
}

Standard-Anforderungsheader

Die Standard-Header-Felder lauten wie folgt.

{
    "header": {
        "auth": {                 
            "token": string,    // end user's Access Token
            "type": ENUM ["OAuth2.0"], 
        }
    }
}

Jede API, die von einem Connector gehostet wird, muss die folgenden Header-Parameter verarbeiten:

Standard-Header und -felder

Feld	Erforderlich/optional	Beschreibung
header:auth	Ja	Autorisierungsinformationen, die vom C2C-Steckverbinderhersteller bei der Registrierung des Connectors bereitgestellt wurden.
header:auth:token	Ja	Autorisierungstoken des Benutzers, das vom Cloud-Drittanbieter generiert und mit dem verknüpft wurde. connectorAssociationID
header:auth:type	Ja	Die Art der erforderlichen Autorisierung.

Anmerkung

Allen Anfragen an Ihren Connector wird das Zugriffstoken des Endbenutzers angehängt. Sie können davon ausgehen, dass die Kontoverknüpfung zwischen dem Endbenutzer und dem Kunden für verwaltete Integrationen bereits erfolgt ist.

Anforderungs-Nutzlast

Zusätzlich zu den allgemeinen Headern hat jede Anfrage eine Nutzlast. Diese Payload wird zwar eindeutige Felder für jeden Operationstyp haben, aber jede Payload hat eine Reihe von Standardfeldern, die immer vorhanden sein werden.

Payload-Felder anfordern:

• operationName: Der Vorgang einer bestimmten Anfrage, der einem der folgenden Werte entspricht:AWS.ActivateUser,, AWS.SendCommandAWS.DiscoverDevices,AWS.DeactivateUser.

• operationVersion: Jeder Vorgang ist versioniert, um seine Weiterentwicklung im Laufe der Zeit zu ermöglichen und eine stabile Schnittstellendefinition für Konnektoren von Drittanbietern bereitzustellen. Managed Integrations übergibt ein Versionsfeld in der Nutzlast aller Anfragen.

• connectorId: Die ID des Connectors, an den die Anfrage gesendet wurde.

Standard-Antwort-Header

Jeder Vorgang reagiert mit einer Antwort ACK auf verwaltete Integrationen für AWS IoT Device Management, die bestätigt, dass Ihr C2C-Connector die Anfrage empfangen und mit der Bearbeitung begonnen hat. Im Folgenden finden Sie ein allgemeines Beispiel für diese Antwort:

{
 	"header":{
 		"responseCode": 200 
 	},
 	"payload":{
 		"responseMessage": “Example response!”
 	}
}

Jede Operationsantwort muss den folgenden gemeinsamen Header haben:

{
    "header": {
        "responseCode": Integer
    }
}

In der folgenden Tabelle ist der Standard-Antwort-Header aufgeführt:

Standard-Antwort-Header und -Feld

Feld	Erforderlich/optional	Kommentar
header:responseCode	Ja	ENUM von Werten, die den Ausführungsstatus der Anfrage angeben.

In den verschiedenen Connector-Schnittstellen und API-Schemas, die in diesem Dokument beschrieben werden, gibt es ein responseMessage Oder-Feld. Message Dies ist ein optionales Feld, das für den C2C-Konnektor Lambda verwendet wird, um mit jedem Kontext bezüglich der Anfrage und ihrer Ausführung zu antworten. Vorzugsweise 200 sollten alle Fehler, die zu einem anderen Statuscode führen, einen Nachrichtenwert enthalten, der den Fehler beschreibt.

Beantworten Sie Anfragen zum Betrieb des C2C-Connectors mit der API SendConnectorEvent

Managed Integrations for AWS IoT Device Management erwartet, dass sich Ihr Connector bei jedem AND-Vorgang asynchron verhält. AWS.SendCommand AWS.DiscoverDevices Das bedeutet, dass die erste Antwort auf diese Operationen lediglich „bestätigt“, dass Ihr C2C-Connector die Anfrage erhalten hat.

Unter Verwendung der SendConnectorEvent API wird von Ihrem Connector erwartet, dass er die Ereignistypen aus der folgenden Liste an für AWS.DiscoverDevices und AWS.SendCommand Operationen sowie an proaktive Geräteereignisse (z. B. manuelles Ein- und Ausschalten eines Lichts) sendet. Eine ausführliche Erläuterung dieser Ereignistypen und ihrer Anwendungsfälle finden Sie unter Implementieren Sie das AWS. DiscoverDevices BetriebImplementieren Sie das AWS. SendCommand Betrieb, undGeräteereignisse mit der API senden SendConnectorEvent.

Wenn Ihr C2C-Connector beispielsweise eine DiscoverDevices Anfrage empfängt, erwartet Managed Integrations for AWS IoT Device Management, dass er synchron mit dem oben definierten Antwortformat reagiert. Anschließend müssen Sie die SendConnectorEvent API mit der in definierten Anforderungsstruktur für ein Implementieren Sie das AWS. DiscoverDevices Betrieb DEVICE_DISCOVERY-Ereignis aufrufen. Der SendConnectorEvent On-API-Aufruf kann überall dort erfolgen, wo Sie Zugriff auf Ihre AWS-Konto Lambda-Anmeldeinformationen für den C2C-Connector haben. Die Geräteerkennung ist erst erfolgreich, wenn Managed Integrations for AWS IoT Device Management dieses Ereignis empfängt.

Anmerkung

Alternativ kann der SendConnectorEvent API-Aufruf bei Bedarf vor der Lambda-Aufrufreaktion des C2C-Konnektors erfolgen. Dieser Ablauf widerspricht jedoch dem asynchronen Modell für die Softwareentwicklung.

• SendConnectorEvent- Ihr Connector nennt dies verwaltete Integrationen für die AWS-IoT-Gerätemanagement-API, um Geräteereignisse an verwaltete Integrationen für AWS IoT Device Management zu senden. Nur 3 Arten von Ereignissen werden von verwalteten Integrationen akzeptiert:

  • "DEVICE_DISCOVERY" — Dieser Ereignisvorgang wird verwendet, um eine Liste der erkannten Geräte in der Drittanbieter-Cloud für ein bestimmtes Zugriffstoken zu senden.

  • „DEVICE_COMMAND_RESPONSE" — Diese Ereignisoperation soll verwendet werden, um ein bestimmtes Geräteereignis als Ergebnis der Befehlsausführung zu senden.

  • „DEVICE_EVENT" — Diese Ereignisoperation muss für jedes Ereignis verwendet werden, das vom Gerät ausgeht und nicht das direkte Ergebnis eines benutzerbasierten Befehls ist. Dies kann als allgemeiner Ereignistyp dienen, um proaktiv Gerätestatusänderungen oder Benachrichtigungen zu melden.