CloudFormation Referenz für benutzerdefinierte Ressourcenanfragen und Antworten - AWS CloudFormation
Einrichtung der VorlageObjekt anfordernAntwortobjekt

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.

CloudFormation Referenz für benutzerdefinierte Ressourcenanfragen und Antworten

CloudFormation verwaltet benutzerdefinierte Ressourcen über ein Request-Response-Protokoll, das mit Ihrem Anbieter für benutzerdefinierte Ressourcen kommuniziert. Jede Anfrage umfasst einen Anforderungstyp (CreateUpdate, oderDelete) und folgt diesem allgemeinen Arbeitsablauf:

  1. Ein Vorlagenentwickler definiert eine benutzerdefinierte Ressource mit einem ServiceToken und ServiceTimeout in der Vorlage und initiiert einen Stack-Vorgang.

  2. CloudFormation sendet über SNS oder Lambda eine JSON-Anfrage an den Anbieter benutzerdefinierter Ressourcen.

  3. Der benutzerdefinierte Ressourcenanbieter verarbeitet die Anfrage und gibt eine JSON-Antwort an eine vorsignierte Amazon S3 S3-Bucket-URL zurück, bevor der Timeout-Zeitraum abläuft.

  4. CloudFormation liest die Antwort und fährt mit dem Stack-Vorgang fort. Wenn vor Ablauf des Timeouts keine Antwort eingeht, gilt die Anfrage als nicht erfolgreich und der Stack-Vorgang schlägt fehl.

Weitere Informationen finden Sie unter So funktionieren benutzerdefinierte Ressourcen.

In diesem Abschnitt werden die Struktur, die Parameter und die erwarteten Antworten für jeden Anforderungstyp beschrieben.

Anmerkung

Die Gesamtgröße des Antworttexts darf 4 096 Bytes nicht überschreiten.

Einrichtung der Vorlage

Bei der Definition einer benutzerdefinierten Ressource in einer Vorlage verwendet AWS::CloudFormation::CustomResourceder Vorlagenentwickler die folgenden Eigenschaften:

ServiceToken

Ein Amazon SNS SNS-Themen-ARN oder eine Lambda-Funktions-ARN aus derselben Region wie der Stack.

Erforderlich: Ja

Typ: Zeichenfolge

ServiceTimeout

Die maximale Zeit in Sekunden, bis das Timeout eines benutzerdefinierten Ressourcenvorgangs abläuft. Es muss ein Wert zwischen 1 und 3600 sein. Standard: 3600 Sekunden (1 Stunde).

Required: No

Typ: Zeichenfolge

Zusätzliche Ressourceneigenschaften werden unterstützt. Ressourceneigenschaften werden wie ResourceProperties in der Anfrage enthalten sein. Der benutzerdefinierte Ressourcenanbieter muss ermitteln, welche Eigenschaften gültig sind und welche Werte zulässig sind.

Objekt anfordern

Create

Wenn der Vorlagenentwickler einen Stapel erstellt, der eine benutzerdefinierte Ressource enthält, CloudFormation sendet er eine Anfrage mit der RequestType Einstellung aufCreate.

Erstellenanforderungen enthalten die folgenden Felder:

RequestType

Create.

Erforderlich: Ja

Typ: Zeichenfolge

RequestId

Eine eindeutige ID für die Anforderung.

Kombinieren Sie StackId mit RequestId und es bildet sich ein Wert, mit dem Sie eine Anforderung für eine bestimmte benutzerdefinierte Ressource eindeutig identifizieren können.

Erforderlich: Ja

Typ: Zeichenfolge

StackId

Der Amazon-Ressourcenname (ARN), der den Stack identifiziert, der die benutzerdefinierte Ressource enthält.

Kombinieren Sie StackId mit RequestId und es bildet sich ein Wert, mit dem Sie eine Anforderung für eine bestimmte benutzerdefinierte Ressource eindeutig identifizieren können.

Erforderlich: Ja

Typ: Zeichenfolge

ResponseURL

Die Antwort-URL identifiziert einen vorsignierten S3-Bucket, der Antworten vom Anbieter für benutzerdefinierte Ressourcen empfängt. CloudFormation

Erforderlich: Ja

Typ: Zeichenfolge

ResourceType

Der vom Developer der Vorlagen gewählte Ressourcentyp der benutzerdefinierten Ressource in der CloudFormation -Vorlage. Namen für benutzerdefinierte Ressourcentypen dürfen bis zu 60 Zeichen lang sein und sowohl alphanumerische Zeichen als auch folgende Zeichen enthalten: _@-.

Erforderlich: Ja

Typ: Zeichenfolge

LogicalResourceId

Der vom Entwickler der Vorlagen gewählte Name (logische ID) der benutzerdefinierten Ressource in der CloudFormation -Vorlage.

Erforderlich: Ja

Typ: Zeichenfolge

ResourceProperties

Dieses Feld enthält den Inhalt des Properties-Objekts, das vom Vorlagen-Entwickler gesendet wurde. Sein Inhalt wird durch benutzerdefinierte Ressourcenanbieter definiert.

Required: No

Typ: JSON-Objekt

Beispiel

{
   "RequestType" : "Create",
   "RequestId" : "unique-request-id",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
   "ResponseURL" : "pre-signed-url-for-create-response",
   "ResourceType" : "Custom::MyCustomResourceType",
   "LogicalResourceId" : "resource-logical-id",
   "ResourceProperties" : {
      "key1" : "string",
      "key2" : [ "list" ],
      "key3" : { "key4" : "map" }
   }
}
Update

Wenn der Vorlagenentwickler Änderungen an den Eigenschaften einer benutzerdefinierten Ressource innerhalb der Vorlage vornimmt und den Stack aktualisiert, CloudFormation sendet er eine Anfrage an den Anbieter für benutzerdefinierte Ressourcen mit der RequestType Einstellung aufUpdate. Das bedeutet, dass Ihr benutzerdefinierter Ressourcencode keine Änderungen in den Ressourcen erkennen muss, da er weiß, dass sich seine Eigenschaften geändert haben, wenn der Anfragetyp Updateist.

Aktualisierungsanforderungen enthalten die folgenden Felder:

RequestType

Update.

Erforderlich: Ja

Typ: Zeichenfolge

RequestId

Eine eindeutige ID für die Anforderung.

Kombinieren Sie StackId mit RequestId und es bildet sich ein Wert, mit dem Sie eine Anforderung für eine bestimmte benutzerdefinierte Ressource eindeutig identifizieren können.

Erforderlich: Ja

Typ: Zeichenfolge

StackId

Der Amazon-Ressourcenname (ARN), der den Stack identifiziert, der die benutzerdefinierte Ressource enthält.

Kombinieren Sie StackId mit RequestId und es bildet sich ein Wert, mit dem Sie eine Anforderung für eine bestimmte benutzerdefinierte Ressource eindeutig identifizieren können.

Erforderlich: Ja

Typ: Zeichenfolge

ResponseURL

Die Antwort-URL identifiziert einen vorsignierten S3-Bucket, der Antworten vom Anbieter für benutzerdefinierte Ressourcen empfängt. CloudFormation

Erforderlich: Ja

Typ: Zeichenfolge

ResourceType

Der vom Developer der Vorlagen gewählte Ressourcentyp der benutzerdefinierten Ressource in der CloudFormation -Vorlage. Namen für benutzerdefinierte Ressourcentypen dürfen bis zu 60 Zeichen lang sein und sowohl alphanumerische Zeichen als auch folgende Zeichen enthalten: _@-. Bei einer Aktualisierung kann der Typ nicht geändert werden.

Erforderlich: Ja

Typ: Zeichenfolge

LogicalResourceId

Der vom Entwickler der Vorlagen gewählte Name (logische ID) der benutzerdefinierten Ressource in der CloudFormation -Vorlage.

Erforderlich: Ja

Typ: Zeichenfolge

PhysicalResourceId

Eine benutzerdefinierte, vom Ressourcenanbieter definierte physische ID, die für diesen Anbieter eindeutig ist.

Erforderlich: Ja

Typ: Zeichenfolge

ResourceProperties

Dieses Feld enthält den Inhalt des Properties-Objekts, das vom Vorlagen-Entwickler gesendet wurde. Sein Inhalt wird durch benutzerdefinierte Ressourcenanbieter definiert.

Required: No

Typ: JSON-Objekt

OldResourceProperties

Wird nur für Update-Anforderungen verwendet. Gibt die bisherigen Ressourceneigenschafts-Werte an, die der Vorlagenentwickler zu einem früheren Zeitpunkt in der CloudFormation -Vorlage deklariert hatte.

Erforderlich: Ja

Typ: JSON-Objekt

Beispiel

{
   "RequestType" : "Update",
   "RequestId" : "unique-request-id",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
   "ResponseURL" : "pre-signed-url-for-update-response",
   "ResourceType" : "Custom::MyCustomResourceType",
   "LogicalResourceId" : "resource-logical-id",
   "PhysicalResourceId" : "provider-defined-physical-id",
   "ResourceProperties" : {
      "key1" : "new-string",
      "key2" : [ "new-list" ],
      "key3" : { "key4" : "new-map" }
   },
   "OldResourceProperties" : {
      "key1" : "string",
      "key2" : [ "list" ],
      "key3" : { "key4" : "map" }
   }
}
Delete

Wenn der Vorlagenentwickler den Stack löscht oder die benutzerdefinierte Ressource aus der Vorlage entfernt und dann den Stapel aktualisiert, CloudFormation sendet er eine Anfrage mit RequestType der Einstellung auf. Delete

Anforderungen zum Löschen enthalten die folgenden Felder:

RequestType

Delete.

Erforderlich: Ja

Typ: Zeichenfolge

RequestId

Eine eindeutige ID für die Anforderung.

Erforderlich: Ja

Typ: Zeichenfolge

StackId

Der Amazon-Ressourcenname (ARN), der den Stack identifiziert, der die benutzerdefinierte Ressource enthält.

Erforderlich: Ja

Typ: Zeichenfolge

ResponseURL

Die Antwort-URL identifiziert einen vorsignierten S3-Bucket, der Antworten vom Anbieter für benutzerdefinierte Ressourcen empfängt. CloudFormation

Erforderlich: Ja

Typ: Zeichenfolge

ResourceType

Der vom Developer der Vorlagen gewählte Ressourcentyp der benutzerdefinierten Ressource in der CloudFormation -Vorlage. Namen für benutzerdefinierte Ressourcentypen dürfen bis zu 60 Zeichen lang sein und sowohl alphanumerische Zeichen als auch folgende Zeichen enthalten: _@-.

Erforderlich: Ja

Typ: Zeichenfolge

LogicalResourceId

Der vom Entwickler der Vorlagen gewählte Name (logische ID) der benutzerdefinierten Ressource in der CloudFormation -Vorlage.

Erforderlich: Ja

Typ: Zeichenfolge

PhysicalResourceId

Eine benutzerdefinierte, vom Ressourcenanbieter definierte physische ID, die für diesen Anbieter eindeutig ist.

Erforderlich: Ja

Typ: Zeichenfolge

ResourceProperties

Dieses Feld enthält den Inhalt des Properties-Objekts, das vom Vorlagen-Entwickler gesendet wurde. Sein Inhalt wird durch benutzerdefinierte Ressourcenanbieter definiert.

Required: No

Typ: JSON-Objekt

Beispiel

{
   "RequestType" : "Delete",
   "RequestId" : "unique-request-id",
   "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
   "ResponseURL" : "pre-signed-url-for-delete-response",
   "ResourceType" : "Custom::MyCustomResourceType",
   "LogicalResourceId" : "resource-logical-id",
   "PhysicalResourceId" : "provider-defined-physical-id",
   "ResourceProperties" : {
      "key1" : "string",
      "key2" : [ "list" ],
      "key3" : { "key4" : "map" }
   }
}

Antwortobjekt

Der benutzerdefinierte Ressourcenanbieter sendet für alle Anforderungstypen eine Antwort an die vorsignierte URL. Wenn der benutzerdefinierte Ressourcenanbieter keine Antwort sendet, CloudFormation wartet er, bis das Zeitlimit für den Vorgang überschritten wird.

Die Antwort muss ein JSON-Objekt mit den folgenden Feldern sein:

Status

Es muss entweder SUCCESS oder FAILED sein.

Erforderlich: Ja

Typ: Zeichenfolge

RequestId

Eine eindeutige ID für die Anforderung. Kopieren Sie diesen Wert genau so, wie er in der Anfrage erscheint.

Erforderlich: Ja

Typ: Zeichenfolge

StackId

Der Amazon-Ressourcenname (ARN), der den Stack identifiziert, der die benutzerdefinierte Ressource enthält. Kopieren Sie diesen Wert genau so, wie er in der Anfrage erscheint.

Erforderlich: Ja

Typ: Zeichenfolge

LogicalResourceId

Der vom Entwickler der Vorlagen gewählte Name (logische ID) der benutzerdefinierten Ressource in der CloudFormation -Vorlage. Kopieren Sie diesen Wert genau so, wie er in der Anfrage erscheint.

Erforderlich: Ja

Typ: Zeichenfolge

PhysicalResourceId

Dieser Wert sollte eine eindeutige Kennung für den Anbieter der benutzerdefinierten Ressource sein und kann bis zu 1 KB groß sein. Der Wert muss eine nicht leere Zeichenfolge sein und muss für alle Antworten für dieselbe Ressource identisch sein.

Beim Aktualisieren von benutzerdefinierten Ressourcen PhysicalResourceId bestimmt der zurückgegebene Wert für das Aktualisierungsverhalten. Wenn der Wert gleich bleibt, wird dies CloudFormation als normales Update betrachtet. Wenn sich der Wert ändert, CloudFormation interpretiert das Update als Ersatz und sendet eine Löschanforderung an die alte Ressource. Weitere Informationen finden Sie unter AWS::CloudFormation::CustomResource.

Erforderlich: Ja

Typ: Zeichenfolge

Reason

Beschreibt den Grund für eine Reaktion auf einen Fehler.

Erforderlich, wenn Status ein FAILED ist. Er ist andernfalls optional.

Required: Conditional

Typ: Zeichenfolge

NoEcho

Gibt an, ob die Ausgabe der benutzerdefinierten Ressource maskiert wird, wenn sie mithilfe der Fn::GetAtt-Funktion abgerufen wird. Wenn diese Option auf true gesetzt ist. werden alle zurückgegebenen Werte mit Sternchen (*****) maskiert außer denen, die im Metadata Abschnitt der Vorlage gespeichert sind. CloudFormation transformiert, ändert oder bearbeitet keine Informationen im Metadata Abschnitt. Der Standardwert ist false.

Weitere Informationen über die Verwendung von NoEcho zur Maskierung sensibler Informationen finden Sie in der bewährten Methode Keine Anmeldeinformationen in Vorlagen einbetten .

Nur für Update Antworten Create und verfügbar. Wird für Delete Antworten nicht unterstützt.

Required: No

Typ: Boolesch

Data

Die vom benutzerdefinierten Ressourcenanbieter definierten Namen-Wert-Paare, die mit der Antwort gesendet werden. Sie können auf die hier namentlich angegebenen Werte in der Vorlage mit Fn::GetAtt zugreifen.

Nur für Create Update Antworten verfügbar. Wird für Delete Antworten nicht unterstützt.

Wichtig

Wenn die Namen-Wert-Paare vertrauliche Informationen enthalten, sollten Sie das NoEcho-Feld benutzen, um die Ausgabe der benutzerdefinierten Ressource zu maskieren. Andernfalls sind die Werte durch APIs diese Oberflächeneigenschaftswerte (z. B.DescribeStackEvents) sichtbar.

Required: No

Typ: JSON-Objekt

Beispiele für erfolgreiche Antworten

Createund Update Antwort

{
   "Status": "SUCCESS",
   "RequestId": "unique-request-id",
   "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
   "LogicalResourceId": "resource-logical-id", 
   "PhysicalResourceId": "provider-defined-physical-id",
   "NoEcho": true,
   "Data": {
      "key1": "value1",
      "key2": "value2"
   }
}

Delete-Antwort

{
   "Status": "SUCCESS",
   "RequestId": "unique-request-id",
   "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
   "LogicalResourceId": "resource-logical-id", 
   "PhysicalResourceId": "provider-defined-physical-id"
}

Beispiel für eine gescheiterte Antwort

{
   "Status": "FAILED",
   "RequestId": "unique-request-id",
   "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
   "LogicalResourceId": "resource-logical-id",
   "PhysicalResourceId": "provider-defined-physical-id",
   "Reason": "Required failure reason string"
}