MQTT-API-Operationen für Jobs und Geräte

Sie können Gerätebefehle für Jobs ausgeben, indem Sie MQTT-Nachrichten auf demReservierte Themen, die für Jobs-Befehle verwendet werden.

Ihr geräteseitiger Client muss die Antwortnachrichtenthemen dieser Befehle abonniert haben. Wenn Sie das verwendenAWS IoTDevice Client, Ihr Gerät abonniert automatisch die Antwortthemen. Das bedeutet, dass der Message Broker die Themen der Antwortnachricht für den Client veröffentlicht, der die Befehlsnachricht veröffentlicht hat, unabhängig davon, ob Ihr Client die Themen der Antwortnachricht abonniert hat oder nicht. Diese Antwortnachrichten passieren den Nachrichtenbroker nicht und können nicht von anderen Clients oder Regeln abonniert werden.

Beim Abonnieren des Jobs undjobExecutionVeranstaltungsthemen für Ihre Flottenüberwachungslösung, zuerst aktivierenEreignisse zum Auftrag und zur Auftragsausführungum alle Ereignisse auf der Cloud-Seite zu empfangen. Meldungen zum Auftragsfortschritt, die über den Nachrichtenbroker verarbeitet werden und verwendet werden können vonAWS IoTRegeln werden veröffentlicht alsAuftragsereignisse. Da der Nachrichtenbroker Antwortnachrichten veröffentlicht, auch ohne ein ausdrückliches Abonnement für diese Nachrichten, muss Ihr Client so konfiguriert sein, dass er die empfangenen Nachrichten empfängt und identifiziert. Ihr Kunde muss auch bestätigen, dassName der SacheIn der eingehenden Nachricht bezieht sich das Thema auf den Dingnamen des Clients, bevor der Client die Nachricht bearbeitet.

Anmerkung

Nachrichten, dieAWS IoTNachrichten, die als Antwort auf MQTT Jobs API-Befehlsmeldungen gesendet werden, werden Ihrem Konto in Rechnung gestellt, unabhängig davon, ob Sie sie ausdrücklich abonniert haben oder nicht.

Im Folgenden werden die MQTT-API-Operationen und ihre Anfrage- und Antwortsyntax gezeigt. Alle MQTT-API-Operationen haben die folgenden Parameter:

clientToken: Ein optionales Client-Token, das verwendet wird, um Anfragen und Antworten zu korrelieren. Geben Sie hier einen beliebigen Wert ein und er wird in der Antwort wiedergegeben.
timestamp: Die Zeit in Sekunden seit der Epoche, als die Nachricht gesendet wurde.

Ruft die Liste aller Jobs ab, die sich nicht in einem Endzustand befinden, für eine bestimmte Sache.

Veröffentlichen Sie zum Aufruf dieser API eine Nachricht auf $aws/things/thingName/jobs/get.

Anforderungsnutzlast:


{ "clientToken": "string" }

Der Message Broker veröffentlicht$aws/things/thingName/jobs/get/acceptedund$aws/things/thingName/jobs/get/rejectedauch ohne ein spezielles Abonnement für sie. Damit Ihr Kunde die Nachrichten empfangen kann, muss er ihnen jedoch zuhören. Weitere Informationen finden Sie unterder Hinweis zu Jobs API-Nachrichten.

Antwortnutzlast:


{
"inProgressJobs" : [ JobExecutionSummary ... ], 
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}

WoinProgressJobsundqueuedJobsgibt eine Liste von zurückJobExecutionSummaryObjekte mit dem Status vonIN_PROGRESSoderQUEUED.

Ruft die nächste ausstehende Auftragsausführung für eine Sache ab und startet sie (Status)IN_PROGRESSoderQUEUED).

Alle Auftragsausführungen mit StatusIN_PROGRESSwerden zuerst zurückgegeben.
Die ausgeführten Jobs werden in der Reihenfolge zurückgegeben, in der sie in die Warteschlange gestellt wurden. Wenn etwas zur Zielgruppe für Ihren Job hinzugefügt oder daraus entfernt wird, überprüfen Sie die Rollout-Reihenfolge aller neuen Auftragsausführungen im Vergleich zu bestehenden Auftragsausführungen.
Wenn die nächste ausstehende Auftragsausführung istQUEUED, sein Zustand ändert sich zuIN_PROGRESSund die Statusdetails der Auftragsausführung werden wie angegeben festgelegt.
Wenn die nächste ausstehende Auftragsausführung bereits erfolgtIN_PROGRESS, seine Statusdetails werden nicht geändert.
Wenn keine Auftragsausführung aussteht, enthält die Antwort nicht dieexecutionFeld.
Optional können Sie einen Schritttimer erstellen, indem Sie einen Wert für denstepTimeoutInMinutesEigentum. Falls Sie den Wert dieser Eigenschaft nicht aktualisieren, indem Sie UpdateJobExecution ausführen, läuft die Auftragsausführung ab, wenn der Schritt-Timer abläuft.

Veröffentlichen Sie zum Aufruf dieser API eine Nachricht auf $aws/things/thingName/jobs/start-next.

Anforderungsnutzlast:


{ 
"statusDetails": {
    "string": "job-execution-state"
    ...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}

statusDetails: Eine Sammlung von Name/Wert-Paaren, die den Status der Auftragsausführung beschreiben. Wenn nicht angegeben, sind die statusDetails nicht geändert.
stepTimeOutInMinutes: Gibt die Dauer an, die dieses Gerät für den Abschluss der Ausführung dieses Auftrags hat. Wenn der Status der Auftragsausführung nicht auf einen Terminalstatus gesetzt wird, bevor dieser Timer abläuft oder bevor der Timer zurückgesetzt wird, (indem SieUpdateJobExecution, setzt den Status aufIN_PROGRESSund Angabe eines neuen Timeout-Werts im FeldstepTimeoutInMinutes) Der Status der Auftragsausführung ist auf gesetztTIMED_OUT. Das Festlegen dieser Zeitüberschreitung hat keinen Einfluss auf die Zeitüberschreitung für die Auftragsausführung, die möglicherweise beim Erstellen des Auftrags festgelegt wurde (CreateJob mithilfe des Feldes timeoutConfig).

Der Message Broker veröffentlicht$aws/things/thingName/jobs/start-next/acceptedund$aws/things/thingName/jobs/start-next/rejectedauch ohne ein spezielles Abonnement für sie. Damit Ihr Kunde die Nachrichten empfangen kann, muss er ihnen jedoch zuhören. Weitere Informationen finden Sie unterder Hinweis zu Jobs API-Nachrichten.

Antwortnutzlast:


{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}

Woexecutionist einJobExecutionObjekt. Beispiele:


{
"execution" : {
    "jobId" : "022",
    "thingName" : "MyThing",
    "jobDocument" : "< contents of job document >",
    "status" : "IN_PROGRESS",
    "queuedAt" : 1489096123309,
    "lastUpdatedAt" : 1489096123309,
    "versionNumber" : 1,
    "executionNumber" : 1234567890
},
"clientToken" : "client-1",
"timestamp" : 1489088524284,
}

Ruft detaillierte Informationen zu einer Auftragsausführung ab.

Sie können das einstellenjobIdzu$nextum die nächste ausstehende Auftragsausführung für eine Sache zurückzugeben (mit einem Status vonIN_PROGRESSoderQUEUED).

Veröffentlichen Sie zum Aufruf dieser API eine Nachricht auf $aws/things/thingName/jobs/jobId/get.

Anforderungsnutzlast:


{ 
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string" 
}

thingName

Der Name des dem Gerät zugeordneten Objekts.

jobId

Die eindeutige Kennung, die diesem Auftrag bei seiner Erstellung zugewiesen wurde.

Oder benutze$nextum die nächste ausstehende Auftragsausführung für eine Sache zurückzugeben (mit einem Status vonIN_PROGRESSoderQUEUED). In diesem Fall alle Jobausführungen mit StatusIN_PROGRESSwerden zuerst zurückgegeben. Auftragsausführungen werden in der Reihenfolge zurückgegeben, in der sie erstellt wurden.

executionNumber

(Optional) Eine Zahl, die eine Auftragsausführung auf einem Gerät identifiziert. Wenn nicht angegeben, wird die letzte Auftragsausführung zurückgegeben.

includeJobDocument

(Optional) Sofern nicht auf gesetztfalse, die Antwort enthält das Stellendokument. Der Standardwert ist true.

Der Message Broker veröffentlicht$aws/things/thingName/jobs/jobId/get/acceptedund$aws/things/thingName/jobs/jobId/get/rejectedauch ohne ein spezielles Abonnement für sie. Damit Ihr Kunde die Nachrichten empfangen kann, muss er ihnen jedoch zuhören. Weitere Informationen finden Sie unterder Hinweis zu Jobs API-Nachrichten.

Antwortnutzlast:


{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}

Woexecutionist einJobExecutionObjekt.

Aktualisiert den Status einer Auftragsausführung. Sie können optional einen Schritt-Timer erstellen, indem Sie einen Wert für die stepTimeoutInMinutes-Eigenschaft angeben. Falls Sie den Wert dieser Eigenschaft nicht aktualisieren, indem Sie UpdateJobExecution erneut ausführen, läuft die Auftragsausführung ab, wenn der Schritt-Timer abläuft.

Veröffentlichen Sie zum Aufruf dieser API eine Nachricht auf $aws/things/thingName/jobs/jobId/update.

Anforderungsnutzlast:


{
"status": "job-execution-state",
"statusDetails": { 
    "string": "string"
    ...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}

status: Der neue Status für die Auftragsausführung (IN_PROGRESS,FAILED,SUCCEEDED, oderREJECTED). Dieser muss bei jeder Aktualisierung angegeben werden.
statusDetails: Eine Sammlung von Name/Wert-Paaren, die den Status der Auftragsausführung beschreiben. Wenn nicht angegeben, sind die statusDetails nicht geändert.
expectedVersion: Die erwartete aktuelle Version der Auftragsausführung. Bei jeder Aktualisierung der Auftragsausführung wird die Version erhöht. Wenn die Version der Auftragsausführung gespeichert ist inAWS IoTDer Job Service passt nicht, das Update wird mit einemVersionMismatchFehler. EinErrorResponsedas die aktuellen Statusdaten zur Auftragsausführung enthält, wird ebenfalls zurückgegeben. (Dadurch ist es nicht erforderlich, eine separate DescribeJobExecution-Anforderung durchzuführen, um die Daten zum Status der Auftragsausführung abzurufen.)
executionNumber: (Optional) Eine Zahl, die eine Auftragsausführung auf einem Gerät identifiziert. Wenn nicht angegeben, wird die letzte Auftragsausführung verwendet.
includeJobExecutionState: (Optional) Wenn enthalten und eingestellt auftrue, die Antwort enthält dieJobExecutionStateFeld. Der Standardwert ist false.
includeJobDocument: (Optional) Wenn enthalten und eingestellt auftrue, die Antwort enthält dieJobDocument. Der Standardwert ist false.
stepTimeoutInMinutes: Gibt die Dauer an, die dieses Gerät für den Abschluss der Ausführung dieses Auftrags hat. Wenn der Auftragsausführungsstatus nicht auf einen Terminalstatus gesetzt wird, bevor dieser Timer abläuft oder bevor der Timer zurückgesetzt wird, wird der Auftragsausführungsstatus auf gesetztTIMED_OUT. Das Festlegen oder Zurücksetzen dieses Timeouts hat keine Auswirkung auf das Zeitlimit für die Auftragsausführung, das möglicherweise bei der Erstellung des Jobs angegeben wurde.

Der Message Broker veröffentlicht$aws/things/thingName/jobs/jobId/update/acceptedund$aws/things/thingName/jobs/jobId/update/rejectedauch ohne ein spezielles Abonnement für sie. Damit Ihr Kunde die Nachrichten empfangen kann, muss er ihnen jedoch zuhören. Weitere Informationen finden Sie unterder Hinweis zu Jobs API-Nachrichten.

Antwortnutzlast:


{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}

executionState: Ein JobExecutionState-Objekt.
jobDocument: Ein -Auftragsdokument-Objekt.
timestamp: Die Zeit in Sekunden seit der Epoche, als die Nachricht gesendet wurde.
clientToken: Ein Client-Token zur Korrelierung von Anforderungen und Antworten.

Wenn Sie das MQTT-Protokoll verwenden, können Sie auch die folgenden Updates durchführen:

Wird gesendet, wenn eine Auftragsausführung der Liste ausstehender Auftragsausführungen für ein Objekt hinzugefügt oder daraus entfernt wird.

Verwenden Sie das -Thema:

$aws/things/thingName/jobs/notify

Nachrichtennutzlast:


{
"jobs" : {
    "JobExecutionState": [ JobExecutionSummary ... ]
         },
    "timestamp": timestamp
}

Wird gesendet, wenn sich ändert, welche Auftragsausführung als nächstes auf der Liste der ausstehenden Auftragsausführungen für eine Sache steht, wie definiert fürDescribeJobExecutionmitjobId $next. Diese Nachricht wird nicht gesendet, wenn sich die Ausführungsdetails des nächsten Jobs ändern, sondern nur, wenn der nächste Job, der zurückgegeben werden würdeDescribeJobExecutionmitjobId $nexthat sich geändert. Betrachten Sie die Auftragsausführungen J1 und J2 mit einem Status vonQUEUED. J1 ist die nächste ausstehende Auftragsausführung auf der Liste. Wenn der Status von J2 geändert wird inIN_PROGRESSwährend der Status von J1 unverändert bleibt, wird diese Benachrichtigung gesendet und enthält Details zu J2.

Verwenden Sie das -Thema:

$aws/things/thingName/jobs/notify-next

Nachrichtennutzlast:


{
"execution" : JobExecution,
"timestamp": timestamp,
}

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

MQTT- und HTTPS-API-Operationen und Datentypen für Jobs, Geräte

HTTP-API für Jobs-Geräte