Jobs, MQTT API Geräteoperationen

Sie können Gerätebefehle für Jobs ausgeben, indem Sie MQTT Nachrichten unter den reservierten Themen veröffentlichen, die für Jobs-Befehle verwendet werden.

Ihr geräteseitiger Client muss die Antwortnachrichten-Themen dieser Befehle abonniert haben. Wenn Sie den AWS IoT Geräteclient verwenden, abonniert Ihr Gerät automatisch die Antwortthemen. Das bedeutet, dass der Message Broker die Themen der Antwortnachricht auf dem 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 werden nicht durch den Message Broker weitergeleitet und können auch nicht von anderen Clients oder Regeln abonniert werden.

Wenn Sie den Auftrag und die jobExecution Ereignisthemen für Ihre Flottenüberwachungslösung abonnieren, aktivieren Sie zunächst die Aufgaben- und Auftragsausführungsereignisse, um alle Ereignisse auf der Cloud-Seite zu empfangen. Auftragsfortschrittsnachrichten, die über den Message Broker verarbeitet werden und von AWS IoT -Regeln verwendet werden können, werden veröffentlicht als Auftragsereignisse. Da der Message Broker Antwortnachrichten auch ohne ausdrückliches Abonnement veröffentlicht, muss Ihr Client so konfiguriert sein, dass er die empfangenen Nachrichten empfängt und identifiziert. Ihr Kunde muss außerdem bestätigen, dass das Thema thingName in der eingehenden Nachricht für den Dingnamen des Kunden gilt, bevor der Client auf die Nachricht reagiert.

Anmerkung

Nachrichten, die als Antwort auf MQTT API Jobs-Befehlsnachrichten AWS IoT 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 Anforderungs- und Antwortsyntax dargestellt. Alle MQTT API Operationen haben die folgenden Parameter:

clientToken: Ein optionaler Client-Token zur Korrelierung von Anforderungen und Antworten. Geben Sie hier einen beliebigen Wert ein, und dieser wird in der Antwort reflektiert.
timestamp: Die Zeit in Sekunden seit der Epoche, in der die Nachricht gesendet wurde, vergangene Zeit.

Ruft die Liste aller Aufträge für ein bestimmtes Objekt ab, die sich nicht in einem Terminal-Zustand befinden.

Um dies aufzurufenAPI, veröffentlichen Sie eine Nachricht am$aws/things/thingName/jobs/get.

Anforderungsnutzlast:


{ "clientToken": "string" }

Der Message Broker veröffentlicht $aws/things/thingName/jobs/get/accepted und $aws/things/thingName/jobs/get/rejected auch ohne ein bestimmtes Abonnement. Damit Ihr Kunde die Nachrichten empfangen kann, muss er sie jedoch abhören. Weitere Informationen finden Sie im Hinweis zu API Jobs-Nachrichten.

Antwortnutzlast:


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

Wenn inProgressJobs und queuedJobs eine Liste von JobExecutionSummary Objekten zurückgibt, die den Status IN_PROGRESS oder QUEUED haben.

Ruft die nächste anstehende Auftragsausführung für ein Objekt ab und startet sie (Status IN_PROGRESS oder QUEUED).

Alle Auftragsausführungen mit dem Status IN_PROGRESS werden zuerst zurückgegeben.
Auftragsausführungen werden in der Reihenfolge zurückgegeben, in der sie zur Warteschlange hinzugefügt wurden. Wenn der Zielgruppe für Ihren Auftrag etwas 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 den Status QUEUED hat, wechselt ihr Status zu IN_PROGRESS, und die Statusdetails der Auftragsausführung werden wie angegeben eingerichtet.
Wenn die nächste ausstehende Auftragsausführung bereits den Status IN_PROGRESS hat, werden ihre Statusdetails nicht geändert.
Wenn keine Auftragsausführungen ausstehen, enthält die Antwort das Feld execution nicht.
Optional können Sie 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 ausführen, läuft die Auftragsausführung ab, wenn der Schritt-Timer abläuft.

Um dies aufzurufenAPI, veröffentlichen Sie eine Nachricht am$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 vor Ablauf oder Zurücksetzen des Timers (durch Aufrufen von UpdateJobExecution, Setzen des Status auf IN_PROGRESS und Angeben eines neuen Zeitüberschreitungswerts im Feld stepTimeoutInMinutes) auf keinen Terminal-Zustand gesetzt wird, wird der Status der Auftragsausführung auf TIMED_OUT gesetzt. 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).

Gültige Werte für diesen Parameter liegen im Bereich von 1 bis 10 080 (1 Minute bis 7 Tage). Ein Wert von -1 ist ebenfalls gültig und beendet den aktuellen Schritttimer (der durch eine frühere Verwendung von erstellt wurde UpdateJobExecutionRequest).

Der Message Broker veröffentlicht $aws/things/thingName/jobs/start-next/accepted und $aws/things/thingName/jobs/start-next/rejected auch ohne ein bestimmtes Abonnement. Damit Ihr Kunde die Nachrichten empfangen kann, muss er sie jedoch abhören. Weitere Informationen finden Sie im Hinweis zu API Job-Nachrichten.

Antwortnutzlast:


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

Wo execution ein JobExecution-Objekt ist. Beispielsweise:


{
"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 die jobId auf $next setzen, um die nächste ausstehende Auftragsausführung für ein Objekt (mit Status IN_PROGRESS oder QUEUED) zurückzugeben.

Um dies aufzurufenAPI, veröffentlichen Sie eine Nachricht am$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.

Sie können $next verwenden, um die nächste ausstehende Auftragsausführung für ein Objekt (mit Status IN_PROGRESS oder QUEUED) zurückzugeben. In diesem Fall werden alle Auftragsausführungen mit dem Status IN_PROGRESS zuerst zurückgegeben. Auftragsausführungen werden in der Reihenfolge zurückgegeben, in der sie erstellt wurden.

executionNumber

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

includeJobDocument

(Optional) Sofern nicht auf false gesetzt, enthält die Antwort das Auftragsdokument. Der Standardwert ist true.

Der Message Broker veröffentlicht $aws/things/thingName/jobs/jobId/get/accepted und $aws/things/thingName/jobs/jobId/get/rejected auch ohne ein bestimmtes Abonnement. Damit Ihr Kunde die Nachrichten empfangen kann, muss er sie jedoch abhören. Weitere Informationen finden Sie im Hinweis zu API Jobs-Nachrichten.

Antwortnutzlast:


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

Wo execution ein JobExecution-Objekt ist.

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.

Um dies aufzurufenAPI, veröffentlichen Sie eine Nachricht am$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 oder REJECTED). 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 im AWS IoT Jobs Service gespeicherte Version der Jobausführung nicht übereinstimmt, wird das Update mit einem VersionMismatch Fehler abgelehnt. Eine ErrorResponse, die den aktuellen Status der 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 Nummer, die eine Auftragsausführung auf einem Gerät identifiziert. Wenn nicht angegeben, wird die letzte Auftragsausführung verwendet.
includeJobExecutionState: (Optional) Wenn enthalten und auf true gesetzt, enthält die Antwort das Feld JobExecutionState. Der Standardwert ist false.
includeJobDocument: (Optional) Wenn enthalten und auf true gesetzt, enthält die Antwort das JobDocument. 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 Status der Auftragsausführung nicht in einen Terminal-Zustand gesetzt wird, bevor dieser Timer abläuft oder bevor der Timer zurückgesetzt wird, wird der Status der Auftragsausführung auf TIMED_OUT gesetzt. Das Festlegen oder Zurücksetzen dieser Zeitüberschreitung hat keinen Einfluss auf die Zeitüberschreitung der Auftragsausführung, die möglicherweise beim Erstellen des Auftrags festgelegt wurde.

Der Message Broker veröffentlicht $aws/things/thingName/jobs/jobId/update/accepted und $aws/things/thingName/jobs/jobId/update/rejected auch ohne ein bestimmtes Abonnement. Damit Ihr Kunde die Nachrichten empfangen kann, muss er sie jedoch abhören. Weitere Informationen finden Sie im Hinweis zu API Jobnachrichten.

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, in der die Nachricht gesendet wurde, vergangene Zeit.
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 die nächste auf der Liste der ausstehenden Auftragsausführungen für ein Objekt ist, wie für DescribeJobExecution mit jobId $next definiert. Diese Nachricht wird nicht gesendet, wenn sich die Details der nächsten Auftragsausführung ändern, sondern nur, wenn sich der nächste Auftrag geändert hat, der von DescribeJobExecution mit jobId $next ausgegeben würde. Nehmen wir als Beispiel die Auftragsausführungen J1 und J2 mit dem Status QUEUED. J1 ist die nächste ausstehende Auftragsausführung auf der Liste. Wenn sich der Status von J2 zu IN_PROGRESS ändert und der Status von J1 unverändert bleibt, wird diese Benachrichtigung gesendet und enthält Details von 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

Jobs, Geräte MQTT und HTTPS API Operationen sowie Datentypen

Jobs-Gerät HTTP API