Changelog der Resolver-Mapping-Vorlage

Anmerkung

Wir unterstützen jetzt hauptsächlich die APPSYNC_JS-Laufzeit und ihre Dokumentation. Bitte erwägen Sie, die APPSYNC_JS-Laufzeit und ihre Anleitungen hier zu verwenden.

Resolver- und Funktionszuweisungsvorlagen sind versioniert. Die Version der Zuordnungsvorlage (z. B.2018-05-29) bestimmt Folgendes: * Die erwartete Form der Konfiguration der Datenquellenanforderung, die von der Anforderungsvorlage bereitgestellt wird. * Das Ausführungsverhalten der Vorlage für die Anforderungszuweisung und der Vorlage für die Antwortzuordnung

Versionen werden im JJJJ-MM-TT-Format dargestellt, wobei ein späteres Datum einer neueren Version entspricht. Auf dieser Seite werden die Unterschiede zwischen den Versionen der Zuordnungsvorlagen aufgeführt, die derzeit in AWS AppSync unterstützt werden.

Matrix der Verfügbarkeit von Datenquellenoperationen pro Version

Operation/Unterstützte Version	2017-02-28	2018-05-29
AWS LambdaAufrufen	Ja	Ja
AWS Lambda BatchInvoke	Ja	Ja
Keine Datenquelle	Ja	Ja
Amazon OpenSearch GET	Ja	Ja
Amazon OpenSearch POST	Ja	Ja
Amazon OpenSearch PUT	Ja	Ja
Amazon OpenSearch LÖSCHEN	Ja	Ja
Amazon OpenSearch GET	Ja	Ja
DynamoDB GetItem	Ja	Ja
DynamoDB Scan	Ja	Ja
DynamoDB Query	Ja	Ja
DynamoDB DeleteItem	Ja	Ja
DynamoDB PutItem	Ja	Ja
DynamoDB BatchGetItem	Nein	Ja
DynamoDB BatchPutItem	Nein	Ja
DynamoDB BatchDeleteItem	Nein	Ja
HTTP	Nein	Ja
Amazon RDS	Nein	Ja

Hinweis: In Funktionen wird zurzeit nur die Version 2018-05-29 unterstützt.

Änderung der Version in einer Unit-Resolver-Zuweisungsvorlage

Für Unit-Resolver wird die Version als Teil des Texts der Zuweisungsvorlage für Anforderungen angegeben. Die Version aktualisieren Sie, indem Sie einfach das Feld version mit der neuen Version aktualisieren.

Um beispielsweise die Version der Vorlage zu aktualisieren: AWS Lambda

{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $utils.toJson($context.arguments)
    }
}

Sie müssen das Versionsfeld wie folgt von 2017-02-28 in 2018-05-29 aktualisieren:

{
    "version": "2018-05-29", ## Note the version
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $utils.toJson($context.arguments)
    }
}

Änderung der Version in einer Funktion

Für Funktionen wird die Version im Feld functionVersion des Funktionsobjekts angegeben. Um die Version zu aktualisieren, aktualisieren Sie einfach functionVersion: Hinweis: Zurzeit wird für die Funktion nur 2018-05-29 unterstützt.

Im Folgenden finden Sie ein Beispiel für einen CLI-Befehl zur Aktualisierung einer vorhandenen Funktionsversion:

aws appsync update-function \
--api-id REPLACE_WITH_API_ID \
--function-id REPLACE_WITH_FUNCTION_ID \
--data-source-name "PostTable" \
--function-version "2018-05-29" \
--request-mapping-template "{...}" \
--response-mapping-template "\$util.toJson(\$ctx.result)"

Hinweis: Es wird empfohlen, das Versionsfeld der Zuweisungsvorlage für Anforderungen der Funktion leer zu lassen, da es nicht berücksichtigt wird. Wenn Sie in einer Zuweisungsvorlage für Anforderungen in einer Funktion eine Version angeben, wird der Versionswert durch den Wert des Feldes functionVersion überschrieben.

2018-05-29

Verhaltensänderung

• Wenn das Ergebnis des Aufrufs der Datenquelle null ist, wird die Zuweisungsvorlage für Antworten ausgeführt.

• Wenn der Aufruf der Datenquelle zu einem Fehler führt, müssen Sie sich jetzt um die Fehlerbehandlung kümmern, da das von der Zuweisungsvorlage für Antworten ausgewertete Ergebnis immer im Block data der GraphQL-Antwort platziert wird.

Reasoning

• null als Ergebnis eines Aufrufs hat eine Bedeutung und für einige Anwendungsfälle müssen null-Ergebnisse daher besonders behandelt werden. Eine Anwendung prüft möglicherweise, ob ein Datensatz in einer Amazon DynamoDB-Tabelle vorhanden ist, um einige Autorisierungsprüfungen durchzuführen. In diesem Fall würde das null-Ergebnis eines Aufrufs dazu führen, dass der Benutzer möglicherweise nicht autorisiert werden kann. Das Ausführen der Zuweisungsvorlage für Antworten bietet jetzt die Möglichkeit, einen Fehler wegen fehlender Autorisierung auszulösen. Dieses Verhalten bietet mehr Kontrolle für API-Designer.

Nehmen wir die folgende Zuweisungsvorlage für Antworten:

$util.toJson($ctx.result)

Mit 2017-02-28 war es bisher so, dass die Zuweisungsvorlage für Antworten nicht ausgeführt wurde, wenn $ctx.result mit null zurückgegeben wurde. Mit 2018-05-29 können wir dieses Szenario jetzt behandeln. Wir können z. B. wie folgt einen Autorisierungsfehler auslösen:

# throw an unauthorized error if the result is null
#if ( $util.isNull($ctx.result) )
    $util.unauthorized()
#end
$util.toJson($ctx.result)

Hinweis: Fehler, die von einer Datenquelle zurückgegeben werden, sind manchmal nicht schwerwiegend oder werden sogar erwartet, daher sollte die Zuweisungsvorlage für Antworten die Flexibilität bieten, den Aufruffehler zu behandeln und zu entscheiden, ob er ignoriert oder erneut ausgelöst wird oder ob ein anderer Fehler auslöst wird.

Nehmen wir die folgende Zuweisungsvorlage für Antworten:

$util.toJson($ctx.result)

Mit 2017-02-28 wurde im Fall eines Aufruffehlers die Zuweisungsvorlage für Antworten ausgewertet und das Ergebnis automatisch im Block errors der GraphQL-Antwort platziert. Mit 2018-05-29 können Sie jetzt entscheiden, wie mit dem Fehler verfahren wird, ihn erneut auslösen oder ihn beim Zurückgegeben der Daten anfügen.

Erneutes Auslösen eines Aufruffehlers

In der folgenden Antwortvorlage lösen wir erneut den Fehler aus, der von der Datenquelle zurückgegeben wurde.

#if ( $ctx.error )
    $util.error($ctx.error.message, $ctx.error.type)
#end
$util.toJson($ctx.result)

Im Fall eines Aufruffehlers (wenn z. B. $ctx.error vorhanden ist) sieht der Antwortblock wie folgt aus:

{
    "data": {
        "getPost": null
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "DynamoDB:ConditionalCheckFailedException",
            "message": "Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}

Auslösen eines anderen Fehlers

In der folgenden Antwortvorlage lösen wir einen eigenen, benutzerdefinierten Fehler aus, nachdem der von der Datenquelle zurückgegebene Fehler verarbeitet wurde.

#if ( $ctx.error )
    #if ( $ctx.error.type.equals("ConditionalCheckFailedException") )
        ## we choose here to change the type and message of the error for ConditionalCheckFailedExceptions
        $util.error("Error while updating the post, try again. Error: $ctx.error.message", "UpdateError")
    #else
        $util.error($ctx.error.message, $ctx.error.type)
    #end
#end
$util.toJson($ctx.result)

Im Fall eines Aufruffehlers (wenn z. B. $ctx.error vorhanden ist) sieht der Antwortblock wie folgt aus:

{
    "data": {
        "getPost": null
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "UpdateError",
            "message": "Error while updating the post, try again. Error: Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}

Anfügen eines Fehlers an Rückgabedaten

In der folgenden Antwortvorlage fügen wir den Fehler an, der von der Datenquelle zurückgegeben wurde, während wird die Daten in der Antwort zurückgeben. Dies wird auch als partielle Antwort bezeichnet.

#if ( $ctx.error )
    $util.appendError($ctx.error.message, $ctx.error.type)
    #set($defaultPost = {id: "1", title: 'default post'})
    $util.toJson($defaultPost)
#else
    $util.toJson($ctx.result)
#end

Im Fall eines Aufruffehlers (wenn z. B. $ctx.error vorhanden ist) sieht der Antwortblock wie folgt aus:

{
    "data": {
        "getPost": {
            "id": "1",
            "title: "A post"
        }
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "ConditionalCheckFailedException",
            "message": "Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}

Migration von 2017-02-28 zu 2018-05-29

Die Migration von 2017-02-28 zu 2018-05-29 ist ganz einfach. Ändern Sie das Versionsfeld der Resolver-Zuweisungsvorlage für Anforderungen oder das Versionsobjekt der Funktion. Beachten Sie jedoch, dass 2018-05-29 ein anderes Ausführungsverhalten zeigt als 2017-02-28. Die Änderungen werden hier erläutert.

Beibehalten des gleichen Ausführungsverhaltens von 2017-02-28 zu 2018-05-29

In einigen Fällen ist es möglich, das Ausführungsverhalten von 2017-02-28 beizubehalten, während eine mit 2018-05-29 versionierte Vorlage ausgeführt wird.

Beispiel: DynamoDB PutItem

Angesichts der folgenden PutItem DynamoDB-Anforderungsvorlage vom 28.02.2017:

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    }
}

Und die folgende Antwortvorlage:

$util.toJson($ctx.result)

Bei der Migration zu 2018-05-29 werden diese Vorlagen wie folgt verändert:

{
    "version" : "2018-05-29", ## Note the new 2018-05-29 version
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    }
}

Und die Antwortvorlage wird wie folgt verändert:

## If there is a datasource invocation error, we choose to raise the same error
## the field data will be set to null.
#if($ctx.error)
  $util.error($ctx.error.message, $ctx.error.type, $ctx.result)
#end

## If the data source invocation is null, we return null.
#if($util.isNull($ctx.result))
  #return
#end

$util.toJson($ctx.result)

Da es jetzt in Ihrer Verantwortung liegt, die Fehler zu behandeln, lösen wird den von DynamoDB zurückgegebenen Fehler mithilfe von $util.error() noch einmal aus. Sie können dieses Snippet anpassen, um Ihre Zuweisungsvorlage in 2018-05-29 zu konvertieren. Beachten Sie, dass Sie bei einer anderen Antwortvorlage die Änderungen des Ausführungsverhaltens berücksichtigen müssen.

Beispiel: DynamoDB GetItem

Angesichts der folgenden GetItem DynamoDB-Anforderungsvorlage vom 28.02.2017:

{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}

Und die folgende Antwortvorlage:

## map table attribute postId to field Post.id
$util.qr($ctx.result.put("id", $ctx.result.get("postId")))

$util.toJson($ctx.result)

Bei der Migration zu 2018-05-29 werden diese Vorlagen wie folgt verändert:

{
    "version" : "2018-05-29", ## Note the new 2018-05-29 version
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}

Und die Antwortvorlage wird wie folgt verändert:

## If there is a datasource invocation error, we choose to raise the same error
#if($ctx.error)
  $util.error($ctx.error.message, $ctx.error.type)
#end

## If the data source invocation is null, we return null.
#if($util.isNull($ctx.result))
  #return
#end

## map table attribute postId to field Post.id
$util.qr($ctx.result.put("id", $ctx.result.get("postId")))

$util.toJson($ctx.result)

In Version 2017-02-28 wurde die Zuweisungsvorlage für Antworten nicht ausgeführt, wenn der Aufruf der Datenquelle null ergeben hatte, was der Fall ist, wenn kein Element in der DynamoDB-Tabelle mit unserem Schlüssel übereinstimmt. Das kann in den meisten Fällen kein Problem sein, wenn $ctx.result jedoch nicht null sein darf, müssen Sie dieses Szenario jetzt behandeln.

2017-02-28

Merkmale

• Wenn das Ergebnis des Aufrufs der Datenquelle null ist, wird die Zuweisungsvorlage für Antworten nicht ausgeführt.

• Wenn der Aufruf der Datenquelle zu einem Fehler führt, wird die Zuweisungsvorlage für Antworten ausgeführt und das ausgewertete Ergebnis wird im Block errors.data der GraphQL-Antwort platziert.