Substitutionsparameter für AWS IoT jobs Vorbereitung des Auftragsdokuments und der Paketversion für die Bereitstellung Benennen der Pakete und Versionen bei der Bereitstellung Zielgruppenzuweisung für Jobs durch AWS IoT Dynamische Objektgruppen Reservierte benannte Schatten- und Paketversionen Deinstallation eines Softwarepakets

Schalten Sie die &Snowball;-Appliance ein, indem Sie auf den Ein-/Aus-Schalter über dem E-Ink-Display drücken. AWS IoT Jobs

AWS IoT Device Management Der Softwarepaketkatalog erweitert AWS IoT Jobs um Substitutionsparameter und die Integration mit AWS IoT Flottenindizierung, dynamischen Dinggruppen und dem AWS IoT reservierten Objekt mit dem Namen Shadow.

Anmerkung

Um alle Funktionen des Softwarepaketkatalogs nutzen zu können, müssen Sie diese AWS Identity and Access Management (IAM-) Rollen und Richtlinien erstellen: AWS IoT Job-Rechte für die Bereitstellung von Paketversionen und AWS IoT Job-Rechte für die Aktualisierung des reservierten benannten Shadows. Weitere Informationen finden Sie unter Vorbereitung der Sicherheit

Substitutionsparameter für AWS IoT jobs

Sie können Substitutionsparameter als Platzhalter in Ihrem AWS IoT Jobdokument verwenden. Wenn der Auftragsservice auf einen Substitutionsparameter stößt, verweist er den Auftrag auf das Attribut einer benannten Softwareversion für den Parameterwert. Sie können diesen Prozess verwenden, um ein einzelnes Auftragsdokument zu erstellen und die Metadaten über allgemeine Attribute an den Auftrag zu übergeben. Sie könnten z. B. eine Amazon Simple Storage Service (Amazon S3) -URL, einen Amazon-Ressourcennamen (ARN) eines Softwarepakets (ARN) oder eine Signatur über Paketversionsattribute an das Auftragsdokument übergeben.

Die Substitutionsparameter sollten im Jobdokument wie folgt formatiert sein:

Name und Version des Softwarepakets
- Die leere Zeichenfolge dazwischen package::version steht für den Substitutionsparameter für den Softwarepaketnamen. Die leere Zeichenfolge dazwischen version::attribute steht für den Substitutionsparameter für die Softwarepaketversion. Sehen Sie sich das folgende Beispiel für die Verwendung des Paketnamens und der Substitutionsparameter für die Paketversion in einem Jobdokument an:. ${aws:iot:package::version::attributes:<attributekey>}
- Das Jobdokument füllt diese Substitutionsparameter automatisch aus, wobei der Versions-ARN aus den Paketversionsdetails verwendet wird. Wenn Sie mithilfe eines API- oder CLI-Befehls einen Job oder eine Auftragsvorlage für eine Bereitstellung mit einem einzelnen Paket erstellen, wird der Versions-ARN für eine Paketversion durch den destinationPackageVersions Parameter in und dargestellt. CreateJob DescribeJob
Alle Attribute für eine Softwarepaketversion
- Sehen Sie sich das folgende Beispiel für die Verwendung aller Attribute eines Substitutionsparameters für eine Softwarepaketversion in einem Jobdokument an: ${aws:iot:package:<packageName>:version:<versionName>:attributes}

Anmerkung

Der Paketname, die Paketversion und alle Substitutionsparameter für Attribute können zusammen verwendet werden. Sehen Sie sich das folgende Beispiel für die Verwendung aller drei Substitutionsparameter in einem Jobdokument an: ${aws:iot:package::version::attributes}

Im folgenden Beispiel gibt es ein Softwarepaket mit dem Namen samplePackage und einer Paketversion mit 2.1.5 den folgenden Attributen:

Name: s3URL, Wert: https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile
- Dieses Attribut identifiziert den Speicherort der Codedatei, die in Amazon S3 gespeichert ist.
Name: signature, Wert: aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj
- Dieses Attribut stellt einen Wert für die Codesignatur bereit, den das Gerät als Sicherheitsmaßnahme benötigt. Weitere Informationen finden Sie unter Codesignatur für Aufträge. Hinweis: Dieses Attribut ist ein Beispiel und nicht als Teil des Softwarepaket-Katalogs oder von Aufträgen erforderlich.

Für s3URL wird der Auftragsdokumentparameter wie folgt geschrieben:


{
"samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}"
}

Für signature wird der Auftragsdokumentparameter wie folgt geschrieben:


{
"samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}"
}

Das vollständige Auftragsdokument ist wie folgt geschrieben:


{
  ...
  "Steps": {
    "uninstall": ["samplePackage"],
    "download": [ 
      { 
        "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}"
      },
    ],
    "signature": [
      "samplePackage" : "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}"
    ]
  }
}

Nachdem die Ersetzung vorgenommen wurde, wird das folgende Auftragsdokument auf den Geräten bereitgestellt:


{
  ...
  "Steps": {
    "uninstall": ["samplePackage"],
    "download": [ 
      { 
        "samplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile"
      },
    ],
    "signature": [
      "samplePackage" : "aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj"
    ]
  }
}

Substitutionsparameter (Vorher- und Nachher-Ansicht)

Substitutionsparameter vereinfachen die Erstellung eines Jobdokuments mithilfe verschiedener Flags, z. B. $default für die Standard-Paketversion. Dadurch entfällt die Notwendigkeit, spezifische Paketversions-Metadaten für jede Auftragsbereitstellung manuell einzugeben, da diese Flags automatisch mit den Metadaten gefüllt werden, auf die in der jeweiligen Paketversion verwiesen wird. Weitere Informationen zu Paketversionsattributen, z. B. $default für die Standard-Paketversion, finden Sie unter. Vorbereitung des Auftragsdokuments und der Paketversion für die Bereitstellung

Klicken Sie während einer Auftragsbereitstellung für eine Paketversion im Fenster des Editors für die Bereitstellungsanweisungsdatei auf die Schaltfläche „Vorschau der Substitution“, um das Auftragsdokument mit und ohne die Substitutionsparameter anzuzeigen. AWS-Managementkonsole

Mithilfe des Parameters „before-substitution“ in den GetJobDocument APIs DescribeJob und können Sie die API-Antwort vor und nach dem Entfernen der Substitutionsparameter anzeigen. Sehen Sie sich die folgenden Beispiele mit den APIs und an: DescribeJob GetJobDocument

DescribeJob

Standardansicht


{
    "jobId": "<jobId>",
    "description": "<description>",
    "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/1.0.2"]
}

Ansicht vor der Substitution


{
    "jobId": "<jobId>",
    "description": "<description>",
    "destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"]
}

GetJobDocument

Standardansicht


{
    "attributes": {
        "location": "prod-artifacts.s3.us-east-1.amazonaws.com/mqtt-core",
        "signature": "IQoJb3JpZ2luX2VjEIrwEaCXVzLWVhc3QtMSJHMEUCIAofPNPpZ9cI",
        "streamName": "mqtt-core",
        "fileId": "0"
    },
}

Ansicht vor der Substitution


{
    "attributes": "${aws:iot:package:TestPackage:version:$default:attributes}",
}

Weitere Informationen über AWS IoT Jobs, das Erstellen von Jobdokumenten und das Bereitstellen von Jobs finden Sie unter Jobs.

Vorbereitung des Auftragsdokuments und der Paketversion für die Bereitstellung

Wenn eine Paketversion erstellt wird, befindet sie sich in einem draft Zustand, der darauf hinweist, dass sie für die Bereitstellung vorbereitet wird. Um die Paketversion für die Bereitstellung vorzubereiten, müssen Sie ein Auftragsdokument erstellen, das Dokument an einem Ort speichern, auf den der Job zugreifen kann (z. B. Amazon S3), und bestätigen, dass die Paketversion die Attributwerte enthält, die das Jobdokument verwenden soll. (Hinweis: Sie können Attribute für eine Paketversion nur aktualisieren, solange sie sich im aktuellen draft Status befindet.)

Wenn Sie einen AWS IoT Job oder eine Job-Vorlage für eine Einzelpaket-Bereitstellung erstellen, haben Sie die folgenden Optionen, um Ihr Jobdokument anzupassen:

Datei mit Anweisungen zur Bereitstellung () recipe

Die Bereitstellungsanweisungsdatei für eine Paketversion enthält die Bereitstellungsanweisungen, einschließlich eines Inline-Jobdokuments, für die Bereitstellung einer Paketversion auf mehreren Geräten. Die Datei ordnet einer Paketversion spezifische Bereitstellungsanweisungen zu, um eine schnelle und effiziente Auftragsbereitstellung zu ermöglichen.

In der AWS-Managementkonsole können Sie die Datei im Vorschaufenster mit den Bereitstellungsanweisungen auf der Registerkarte „Konfigurationen für die Versionsbereitstellung“ des Workflows „Neues Paket erstellen“ erstellen. Sie können die automatische Generierung einer Anweisungsdatei aus den Attributen Ihrer Paketversion nutzen AWS IoT , indem Sie die Option Von AWS IoT empfohlener Datei starten verwenden oder Ihr vorhandenes Auftragsdokument verwenden, das in einem Amazon S3-Bucket gespeichert ist, indem Sie Ihre eigene Bereitstellungsanweisungsdatei verwenden verwenden.

Anmerkung
Wenn Sie Ihr eigenes Auftragsdokument verwenden, können Sie es direkt im Vorschaufenster der Bereitstellungsanweisungsdatei aktualisieren. Ihr ursprüngliches Auftragsdokument, das in Ihrem Amazon S3-Bucket gespeichert ist, wird jedoch nicht automatisch aktualisiert.

Wenn Sie AWS CLI oder verwenden, recipe steht ein API-Befehl wie CreatePackageVersion GetPackageVersionUpdatePackageVersion, oder für die Bereitstellungsanweisungsdatei, die ein integriertes Jobdokument enthält.

Weitere Informationen darüber, was ein Jobdokument ist, finden Sie unterGrundkonzepte.

Im folgenden Beispiel finden Sie die Datei mit den Bereitstellungsanweisungen, wie sie dargestellt wird durchrecipe:
```
{
    "packageName": "sample-package-name",
    "versionName": "sample-package-version",
    ...
    "recipe": "{...}"
}
```
Anmerkung
Die Bereitstellungsanweisungsdatei, wie sie durch dargestellt wird, recipe kann aktualisiert werden, wenn sich eine Paketversion im published Statusstatus befindet, da sie von den Metadaten der Paketversion getrennt ist. Sie wird während des Einsatzes am Arbeitsplatz unveränderlich.

ArtifactVersionsattribut

Mithilfe des Versionsattributs artifact in Ihrer Softwarepaketversion können Sie den Amazon S3-Speicherort für Ihre Paketversionsartefakte hinzufügen. Wenn mithilfe von AWS IoT Jobs eine Auftragsbereitstellung für Ihre Paketversion ausgelöst wird, wird der vorsignierte URL-Platzhalter ${aws:iot:package:<packageName>:version:<versionName>:artifact-location:s3-presigned-url} im Jobdokument mithilfe des Amazon S3-Buckets, des Bucket-Schlüssels und der Version der im Amazon S3-Bucket gespeicherten Datei aktualisiert. Der Amazon-S3-Bucket, in dem die Paketversionsartefakte gespeichert sind, muss sich in derselben Region befinden, in der die Paketversion erstellt wurde.

Anmerkung
Um mehrere Objektversionen derselben Datei in Ihrem Amazon S3-Bucket zu speichern, müssen Sie die Versionierung in Ihrem Bucket aktivieren. Weitere Informationen finden Sie unter Versionierung für Buckets aktivieren.

Um auf die Artefakte der Paketversion im Amazon S3-Bucket zuzugreifen, wenn Sie den CreatePackageVersion oder UpdatePackageVersion API-Vorgang verwenden, benötigen Sie die folgenden Berechtigungen:
```
{
    "Version":"2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObjectVersion",
            "Resource": "arn:aws:s3:::bucket-name/key-name"
        }
    ]
}
```
Weitere Informationen zum Versionsattribut artifact in den CreatePackageVersion und UpdatePackageVersion -API-Vorgängen finden Sie unter CreatePackageVersion und UpdatePackageVersion.

Sehen Sie sich das folgende Beispiel an, das das Versionsattribut zeigt, das den Speicherort des Artefakts in Amazon S3 artifact unterstützt, wenn Sie eine neue Paketversion erstellen:
```
{
    "packageName": "sample package name",
    "versionName": "1.0",
    "artifact": {
        "s3Location": {
            "bucket": "firmware",
            "key": "image.bin",
            "version": "12345"
        }
    }
}
```
Anmerkung
Wenn eine Paketversion von einem draft Statusstatus in einen Statusstatus wechselt, werden die Attribute der Paketversion und der Speicherort der Artefakte unveränderlich. published Um diese Informationen zu aktualisieren, müssen Sie eine neue Paketversion erstellen und diese Aktualisierungen durchführen, während Sie sich im Statusstatus befinden. draft

Paket-Version

Eine Standardversion des Softwarepakets kann in den verfügbaren Versionen des Softwarepakets angegeben werden, die eine sichere und stabile Paketversion bieten. Dies dient als Basisversion des Softwarepakets, wenn Sie mithilfe AWS IoT von Jobs die Standardpaketversion für Ihre Geräteflotte bereitstellen. Wenn Sie einen Auftrag zur Bereitstellung der $default Paketversion für ein Softwarepaket erstellen, müssen die Paketversion im Auftragsdokument und in der neuen Auftragsbereitstellung mit der Version übereinstimmen$default. Die Paketversion in der Auftragsbereitstellung wird durch API destinationPackageVersions - und CLI-Befehle und VersionARN in der dargestellt AWS-Managementkonsole. Die Paketversion im Jobdokument wird durch den folgenden Platzhalter für das Jobdokument dargestellt, der unten abgebildet ist:
```
arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$default
```
Um einen Job oder eine Jobvorlage mit der Standardpaketversion zu erstellen, verwenden Sie das $default Flag im Befehl CreateJob or CreateJobTemplate API, wie unten dargestellt:
```
"$ aws iot create-job \
    --destination-package-versions "arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"
    --document file://jobdoc.json
```
Anmerkung
Das $default Paketversionsattribut, das auf die Standardversion verweist, ist ein optionales Attribut, das nur erforderlich ist, wenn für eine Auftragsbereitstellung über AWS IoT Jobs auf die Standardpaketversion verwiesen wird.

Wenn Sie mit der Paketversion zufrieden sind, veröffentlichen Sie sie entweder über die Seite mit den Softwarepaketdetails in der AWS IoT Konsole oder indem Sie den UpdatePackageVersion API-Vorgang ausführen. Sie können dann auf die Paketversion verweisen, wenn Sie den Job entweder über die AWS IoT Konsole erstellen oder indem Sie den CreateJob API-Vorgang ausführen.

Benennen der Pakete und Versionen bei der Bereitstellung

Um eine Softwarepaketversion auf einem Gerät bereitzustellen, stellen Sie sicher, dass das Softwarepaket und die Paketversion, auf die im Jobdokument verwiesen wird, mit dem Softwarepaket und der Paketversion übereinstimmen, die im destinationPackageVersions Parameter im CreateJob API-Vorgang angegeben sind. Wenn sie nicht übereinstimmen, erhalten Sie eine Fehlermeldung, in der Sie aufgefordert werden, beide Referenzen abzugleichen. Weitere Informationen zu Fehlermeldungen im Softwarepaketkatalog finden Sie unterAllgemeine Fehlermeldungen zur Fehlerbehebung.

Zusätzlich zu den Softwarepaketen und Paketversionen, auf die im Jobdokument verwiesen wird, können Sie zusätzliche Softwarepakete und Paketversionen in den destinationPackageVersions Parameter des CreateJob API-Vorgangs aufnehmen, auf die im Jobdokument nicht verwiesen wird. Stellen Sie sicher, dass das Jobdokument die erforderlichen Installationsinformationen enthält, damit die Geräte die zusätzlichen Softwarepaketversionen ordnungsgemäß installieren können. Weitere Informationen zum CreateJob API-Betrieb finden Sie unter CreateJob.

Zielgruppenzuweisung für Jobs durch AWS IoT Dynamische Objektgruppen

Der Softwarepaketkatalog arbeitet mit Flottenindizierung, AWS IoT Aufträgen und AWS IoT dynamischen Objektgruppen, um Geräte innerhalb Ihrer Flotte zu filtern und gezielt auszuwählen, um auszuwählen, welche Paketversion auf Ihren Geräten bereitgestellt werden soll. Sie können eine Flottenindizierungsabfrage auf der Grundlage der aktuellen Paketinformationen Ihres Geräts ausführen und diese Dinge für einen AWS IoT Auftrag als Targeting auswählen. Sie können auch Softwareupdates veröffentlichen, jedoch nur für geeignete Zielgeräte. Sie können beispielsweise angeben, dass Sie eine Konfiguration nur für die Geräte bereitstellen möchten, auf denen derzeit die iot-device-client 1.5.09 ausgeführt wird. Weitere Informationen finden Sie unter Erstellen einer dynamischen Objektgruppe.

Reservierte benannte Schatten- und Paketversionen

Falls konfiguriert, können AWS IoT Jobs den reservierten Namen shadow ($package) einer Sache aktualisieren, wenn der Job erfolgreich abgeschlossen wurde. In diesem Fall müssen Sie dem reservierten benannten Schatten eines Objekts keine Paketversion manuell zuordnen.

In den folgenden Situationen können Sie sich dafür entscheiden, eine Paketversion manuell dem reservierten benannten Schatten des Objekts zuzuordnen oder zu aktualisieren:

Sie registrieren ein Ding unter, AWS IoT Core ohne die installierte Paketversion zuzuordnen.
AWS IoT Jobs ist nicht so konfiguriert, dass es den reservierten Namen Shadow des Dings aktualisiert.
Sie verwenden einen internen Prozess, um Paketversionen an Ihre Flotte zu versenden, und dieser Prozess wird nicht aktualisiert, AWS IoT Core wenn er abgeschlossen ist.

Anmerkung

Wir empfehlen Ihnen, AWS IoT Jobs zu verwenden, um die Paketversion im reservierten Shadow ($package) zu aktualisieren. Das Aktualisieren des Versionsparameters im $package Shadow durch andere Prozesse (z. B. manuelle oder programmatische API-Aufrufe), wenn AWS IoT Jobs ebenfalls für die Aktualisierung des Shadows konfiguriert ist, kann zu Inkonsistenzen zwischen der tatsächlichen Version auf dem Gerät und der Version führen, die an den reservierten benannten Shadow gemeldet wurde.

Sie können eine Paketversion zum reservierten Schatten ($package) eines Objekts über die Konsole oder den UpdateThingShadow-API-Vorgang hinzufügen oder aktualisieren. Weitere Informationen finden Sie unter Einer Sache eine Paketversion zuordnen. AWS IoT

Anmerkung

Durch das Zuordnen einer Paketversion zu einer AWS IoT Sache wird die Gerätesoftware nicht direkt aktualisiert. Sie müssen die Paketversion auf dem Gerät bereitstellen, um die Gerätesoftware zu aktualisieren.

Deinstallation eines Softwarepakets und seiner Paketversion

$nullist ein reservierter Platzhalter, der den AWS IoT Jobs-Dienst auffordert, das vorhandene Softwarepaket und die Paketversion aus dem reservierten benannten Shadow des Geräts zu entfernen. $package Weitere Informationen finden Sie unter Reservierter benannter Schatten.

Um diese Funktion zu verwenden, ersetzen Sie den Versionsnamen am Ende des PackageVersion Amazon-Ressourcennamens (ARN) des Ziels durch$null. Anschließend müssen Sie Ihren Service anweisen, die Software vom Gerät zu entfernen.

Der autorisierte ARN verwendet das folgende Format:


arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$null

Zum Beispiel


$ aws iot create-job \
    ... \
    --destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"]

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

Vorbereitung der Flottenindizierung

Erste Schritte