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.
Kontextreferenz für Resolver-Mapping-Vorlagen
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.
AWS AppSync definiert eine Reihe von Variablen und Funktionen für die Arbeit mit Resolver-Mapping-Vorlagen. Dies erleichtert logische Operationen an Daten mit GraphQL. In diesem Dokument werden diese Funktionen beschrieben und Beispiele für das Arbeiten mit Vorlagen gegeben.
Zugreifen auf den $context
Die Variable $context
ist eine Zuweisung, die alle Kontextinformationen für den Resolver-Aufruf enthält. Sie hat die folgende Struktur:
{ "arguments" : { ... }, "source" : { ... }, "result" : { ... }, "identity" : { ... }, "request" : { ... }, "info": { ... } }
Anmerkung
Wenn Sie versuchen, über seinen Schlüssel auf einen Wörterbuch-/Map-Eintrag (z. B. einen Eintrag incontext
) zuzugreifen, um den Wert abzurufen, können Sie mit der Velocity Template Language (VTL) die Notation direkt verwenden. <dictionary-element>.<key-name>
Dies funktioniert aber möglicherweise nicht in allen Fällen, z. B. wenn die Schlüsselnamen Sonderzeichen (wie einen Unterstrich "_") enthalten. Wir empfehlen, immer die Notation <dictionary-element>.get("<key-name>")
zu verwenden.
Jedes Feld in der $context
-Zuordnung ist wie folgt definiert:
$context
-Felder
-
arguments
-
Eine Zuordnung, die alle GraphQL-Argumente für dieses Feld enthält.
-
identity
-
Ein Objekt, das Informationen über den Aufrufer enthält. Weitere Informationen zur Struktur dieses Felds finden Sie unter Identity.
-
source
-
Eine Zuordnung, die die Auflösung des übergeordneten Feldes enthält.
-
stash
-
Stash ist eine Zuordnung, die in jeder Resolver- und Funktionszuweisungsvorlage bereitgestellt wird. Eine Stash-Instanz bleibt während einer einzigen Resolver-Instance bestehen. Daher können Sie den Stash nutzen, um beliebige Daten zwischen Zuweisungsvorlagen für Anforderungen und Antworten und Funktionen in einem Pipeline-Resolver zu übergeben. Der Stash bietet dieselben Methoden wie die Java Map
-Datenstruktur.
-
result
-
Ein Container für die Ergebnisse dieses Resolvers. Dieses Feld ist nur für Antwortzuordnungsvorlagen verfügbar.
Wenn Sie beispielsweise das
author
Feld der folgenden Abfrage auflösen:query { getPost(id: 1234) { postId title content author { id name } } }
Dann könnte die vollständige
$context
-Variable, die bei der Verarbeitung einer Antwortzuweisungsvorlage verfügbar ist, folgendermaßen aussehen:{ "arguments" : { id: "1234" }, "source": {}, "result" : { "postId": "1234", "title": "Some title", "content": "Some content", "author": { "id": "5678", "name": "Author Name" } }, "identity" : { "sourceIp" : ["x.x.x.x"], "userArn" : "arn:aws:iam::123456789012:user/appsync", "accountId" : "666666666666", "user" : "AIDAAAAAAAAAAAAAAAAAA" } }
-
prev.result
-
Das Ergebnis einer beliebigen vorherigen Operation, die in einem Pipeline-Resolver ausgeführt wurde.
Wenn es sich bei der vorherigen Operation um die Before-Mapping-Vorlage des Pipeline-Resolvers handelte,
$ctx.prev.result
stellt dies die Ausgabe der Auswertung der Vorlage dar und wird der ersten Funktion in der Pipeline zur Verfügung gestellt.Wenn die vorherige Operation die erste Funktion betraf, steht
$ctx.prev.result
für die Ausgabe der ersten Funktion und wird der zweiten Funktion in der Pipeline zur Verfügung gestellt.Wenn die vorherige Operation die letzte Funktion war, stellt sie die Ausgabe der letzten Funktion
$ctx.prev.result
dar und wird für die After-Mapping-Vorlage des Pipeline-Resolvers verfügbar gemacht. -
info
-
Ein Objekt, das Informationen über die GraphQL-Anforderung enthält. Die Struktur dieses Feldes finden Sie unter Info.
Identität
Der Abschnitt identity
enthält Informationen über den Aufrufer. Die Form dieses Abschnitts hängt von Ihrem AWS AppSync API Autorisierungstyp ab.
Weitere Informationen zu AWS AppSync Sicherheitsoptionen finden Sie unter Autorisierung und Authentifizierung.
-
API_KEY
-Autorisierung -
Das
identity
Feld ist nicht gefüllt. AWS_LAMBDA
-Autorisierung-
Der
identity
enthält denresolverContext
Schlüssel, der denselbenresolverContext
Inhalt enthält, der von der Lambda-Funktion zurückgegeben wurde, die die Anfrage autorisiert. -
AWS_IAM
-Autorisierung -
Der
identity
hat die folgende Form:{ "accountId" : "string", "cognitoIdentityPoolId" : "string", "cognitoIdentityId" : "string", "sourceIp" : ["string"], "username" : "string", // IAM user principal "userArn" : "string", "cognitoIdentityAuthType" : "string", // authenticated/unauthenticated based on the identity type "cognitoIdentityAuthProvider" : "string" // the auth provider that was used to obtain the credentials }
-
AMAZON_COGNITO_USER_POOLS
-Autorisierung -
Der
identity
hat die folgende Form:{ "sub" : "uuid", "issuer" : "string", "username" : "string" "claims" : { ... }, "sourceIp" : ["x.x.x.x"], "defaultAuthStrategy" : "string" }
Jedes Feld ist wie folgt definiert:
-
accountId
-
Die AWS Konto-ID des Anrufers.
-
claims
-
Die Ansprüche, die der Benutzer hat.
-
cognitoIdentityAuthType
-
Entweder authentifiziert oder nicht authentifiziert, basierend auf dem Identitätstyp.
-
cognitoIdentityAuthProvider
-
Eine durch Kommas getrennte Liste mit Informationen zu externen Identitätsanbietern, anhand derer die Anmeldeinformationen abgerufen wurden, mit denen die Anfrage signiert wurde.
-
cognitoIdentityId
-
Die Amazon Cognito Cognito-Identitäts-ID des Anrufers.
-
cognitoIdentityPoolId
-
Die dem Anrufer zugeordnete Amazon Cognito Cognito-Identitätspool-ID.
-
defaultAuthStrategy
-
Die Standardautorisierungsstrategie für diesen Aufrufer (
ALLOW
oderDENY
). -
issuer
-
Der Aussteller des Tokens.
-
sourceIp
-
Die Quell-IP-Adresse des Anrufers, der empfängt. AWS AppSync Wenn die Anfrage den
x-forwarded-for
Header nicht enthält, enthält der Quell-IP-Wert nur eine einzige IP-Adresse aus der TCP Verbindung. Wenn die Anfrage einenx-forwarded-for
Header enthält, ist die Quell-IP zusätzlich zur IP-Adresse aus der TCP Verbindung eine Liste von IP-Adressen aus demx-forwarded-for
Header. -
sub
-
Die UUID des authentifizierten Benutzers.
-
user
-
Der IAM Benutzer.
-
userArn
-
Der Amazon-Ressourcenname (ARN) des IAM Benutzers.
-
username
-
Der Benutzername des authentifizierten Benutzers. Bei einer
AMAZON_COGNITO_USER_POOLS
-Autorisierung ist der Wert des Benutzernamens der Wert des Attributs cognito:username. Im Fall einerAWS_IAM
Autorisierung entspricht der Wert von username dem Wert des AWS Benutzerprinzipals. Wenn Sie die IAM Autorisierung mit Anmeldeinformationen verwenden, die aus Amazon Cognito Cognito-Identitätspools stammen, empfehlen wir Ihnen, diese zu verwenden.cognitoIdentityId
Auf die Header der Anfrage zugreifen
AWS AppSync unterstützt die Übergabe benutzerdefinierter Header von Clients und den Zugriff auf sie in Ihren GraphQL-Resolvern mithilfe von. $context.request.headers
Sie können die Header-Werte dann für Aktionen wie das Einfügen von Daten in eine Datenquelle oder für Autorisierungsprüfungen verwenden. Sie können einzelne oder mehrere Anforderungsheader $curl
mithilfe einer API Taste von der Befehlszeile aus verwenden, wie in den folgenden Beispielen gezeigt:
Beispiel für einen einzelnen Header
Angenommen, Sie legen wie folgt einen custom
-Header mit dem Wert nadia
fest:
curl -XPOST -H "Content-Type:application/graphql" -H "custom:nadia" -H "x-api-key:<API-KEY-VALUE>" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https://<ENDPOINT>/graphql
Darauf könnte dann mit $context.request.headers.custom
zugegriffen werden. Für DynamoDB könnte es beispielsweise wie folgt VTL sein:
"custom": $util.dynamodb.toDynamoDBJson($context.request.headers.custom)
Beispiel für mehrere Header
Sie können auch mehrere Header in einer einzigen Anforderung übergeben und auf diese in der Resolver-Zuweisungsvorlage zugreifen. Zum Beispiel, wenn der custom
Header mit zwei Werten festgelegt ist:
curl -XPOST -H "Content-Type:application/graphql" -H "custom:bailey" -H "custom:nadia" -H "x-api-key:<API-KEY-VALUE>" -d '{"query":"mutation { createEvent(name: \"demo\", when: \"Next Friday!\", where: \"Here!\") {id name when where description}}"}' https://<ENDPOINT>/graphql
Sie können dann darauf als Array zugreifen, z. B. $context.request.headers.custom[1]
.
Anmerkung
AWS AppSync macht den Cookie-Header nicht verfügbar$context.request.headers
.
Greifen Sie auf den angeforderten benutzerdefinierten Domainnamen zu
AWS AppSync unterstützt die Konfiguration einer benutzerdefinierten Domain, mit der Sie auf Ihre GraphQL- und Echtzeit-Endpunkte für Ihre zugreifen können. APIs Wenn Sie eine Anfrage mit einem benutzerdefinierten Domainnamen stellen, können Sie den Domainnamen mithilfe von abrufen. $context.request.domainName
Bei Verwendung des standardmäßigen GraphQL-Endpunktdomänennamens lautet der Wert. null
Informationen
Der Abschnitt info
enthält Informationen über die GraphQL-Anforderung. Dieser Abschnitt hat die folgende Form:
{ "fieldName": "string", "parentTypeName": "string", "variables": { ... }, "selectionSetList": ["string"], "selectionSetGraphQL": "string" }
Jedes Feld ist wie folgt definiert:
-
fieldName
-
Der Name des Feldes, das derzeit aufgelöst wird.
-
parentTypeName
-
Der Name des übergeordneten Typs für das Feld, das derzeit aufgelöst wird.
-
variables
-
Eine Zuordnung, die alle Variablen enthält, die an die GraphQL-Anforderung übergeben werden.
-
selectionSetList
-
Eine Listendarstellung der Felder im GraphQL-Auswahlsatz. Felder mit Aliasnamen werden nur durch den Aliasnamen referenziert, nicht durch den Feldnamen. Im folgenden Beispiel ist dies detailliert dargestellt.
-
selectionSetGraphQL
-
Eine Zeichenkettendarstellung des Auswahlsatzes, formatiert als GraphQL-Schemadefinitionssprache ()SDL. Fragmente werden zwar nicht mit dem Auswahlsatz zusammengeführt, Inline-Fragmente bleiben jedoch erhalten, wie im folgenden Beispiel gezeigt.
Anmerkung
Bei Verwendung von $utils.toJson()
on context.info
werden die Werte that selectionSetGraphQL
und selectionSetList
return standardmäßig nicht serialisiert.
Angenommen, Sie lösen das getPost
-Feld der folgenden Abfrage auf:
query { getPost(id: $postId) { postId title secondTitle: title content author(id: $authorId) { authorId name } secondAuthor(id: "789") { authorId } ... on Post { inlineFrag: comments: { id } } ... postFrag } } fragment postFrag on Post { postFrag: comments: { id } }
Dann könnte die vollständige $context.info
-Variable, die bei der Verarbeitung einer Zuweisungsvorlage verfügbar ist, folgendermaßen aussehen:
{ "fieldName": "getPost", "parentTypeName": "Query", "variables": { "postId": "123", "authorId": "456" }, "selectionSetList": [ "postId", "title", "secondTitle" "content", "author", "author/authorId", "author/name", "secondAuthor", "secondAuthor/authorId", "inlineFragComments", "inlineFragComments/id", "postFragComments", "postFragComments/id" ], "selectionSetGraphQL": "{\n getPost(id: $postId) {\n postId\n title\n secondTitle: title\n content\n author(id: $authorId) {\n authorId\n name\n }\n secondAuthor(id: \"789\") {\n authorId\n }\n ... on Post {\n inlineFrag: comments {\n id\n }\n }\n ... postFrag\n }\n}" }
selectionSetList
macht nur Felder verfügbar, die zum aktuellen Typ gehören. Wenn es sich bei dem aktuellen Typ um eine Schnittstelle oder Union handelt, werden nur ausgewählte Felder angezeigt, die zur Schnittstelle gehören. Nehmen wir zum Beispiel das folgende Schema:
type Query { node(id: ID!): Node } interface Node { id: ID } type Post implements Node { id: ID title: String author: String } type Blog implements Node { id: ID title: String category: String }
Und die folgende Abfrage:
query { node(id: "post1") { id ... on Post { title } ... on Blog { title } } }
$ctx.info.selectionSetList
Beim Aufrufen mit der Query.node
Feldauflösung id
wird nur angezeigt:
"selectionSetList": [ "id" ]
Bereinigung von Eingängen
Anwendungen müssen nicht vertrauenswürdige Eingaben bereinigen, um zu verhindern, dass externe Parteien eine Anwendung anders als beabsichtigt verwenden. Da das Benutzereingaben in Eigenschaften wie$context.arguments
,,, und $context
enthält $context.identity
$context.result
$context.info.variables
, muss darauf geachtet werden$context.request.headers
, dass deren Werte in Mapping-Vorlagen bereinigt werden.
Da Mapping-Vorlagen das darstellenJSON, erfolgt die Bereinigung von Eingaben in der Form, dass JSON reservierte Zeichen in Zeichenketten, die Benutzereingaben darstellen, maskiert werden. Es hat sich bewährt, das $util.toJson()
Hilfsprogramm zu verwenden, um JSON reservierte Zeichen aus sensiblen Zeichenkettenwerten zu maskieren, wenn sie in eine Zuordnungsvorlage eingefügt werden.
In der folgenden Lambda-Anforderungszuordnungsvorlage haben wir beispielsweise, weil wir auf eine unsichere Kundeneingabezeichenfolge ($context.arguments.id
) zugegriffen haben, diese umschlossen, $util.toJson()
um zu verhindern, dass Zeichen ohne JSON Escape-Zeichen die Vorlage beschädigen. JSON
{ "version": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "postId": $util.toJson($context.arguments.id) } }
Im Gegensatz zur unten stehenden Zuordnungsvorlage, bei der wir sie direkt einfügen$context.arguments.id
, ohne sie zu bereinigen. Dies funktioniert nicht für Zeichenketten, die Anführungszeichen ohne Escape-Zeichen oder andere JSON reservierte Zeichen enthalten, und kann dazu führen, dass Ihre Vorlage fehlerhaft wird.
## DO NOT DO THIS { "version": "2017-02-28", "operation": "Invoke", "payload": { "field": "getPost", "postId": "$context.arguments.id" ## Unsafe! Do not insert $context string values without escaping JSON characters. } }