Referenz zur Resolver-Mapping-Vorlage für Lambda

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.

Sie können AWS AppSync Funktionen und Resolver verwenden, um Lambda-Funktionen in Ihrem Konto aufzurufen. Sie können Ihre Anforderungs-Payloads und die Antwort Ihrer Lambda-Funktionen gestalten, bevor Sie sie an Ihre Clients zurückgeben. Sie können auch Zuordnungsvorlagen verwenden, um AWS AppSync Hinweise auf die Art des aufzurufenden Vorgangs zu geben. In diesem Abschnitt werden die verschiedenen Mapping-Vorlagen für die unterstützten Lambda-Operationen beschrieben.

Mapping-Vorlage anfordern

Die Lambda-Anforderungszuordnungsvorlage verarbeitet Felder, die sich auf Ihre Lambda-Funktion beziehen:

{
  "version": string,
  "operation": Invoke|BatchInvoke,
  "payload": any type,
  "invocationType": RequestResponse|Event
}

Dies ist die JSON-Schemadarstellung der Lambda-Anforderungszuordnungsvorlage, wenn sie aufgelöst wurde:

{
  "definitions": {},
  "$schema": "https://json-schema.org/draft-06/schema#",
  "$id": "https://aws.amazon.com/appsync/request-mapping-template.json",
  "type": "object",
  "properties": {
    "version": {
      "$id": "/properties/version",
      "type": "string",
      "enum": [
        "2018-05-29"
      ],
      "title": "The Mapping template version.",
      "default": "2018-05-29"
    },
    "operation": {
      "$id": "/properties/operation",
      "type": "string",
      "enum": [
        "Invoke",
        "BatchInvoke"
      ],
      "title": "The Mapping template operation.",
      "description": "What operation to execute.",
      "default": "Invoke"
    },
    "payload": {},
    "invocationType": {
      "$id": "/properties/invocationType",
      "type": "string",
      "enum": [
        "RequestResponse",
        "Event"
      ],
      "title": "The Mapping template invocation type.",
      "description": "What invocation type to execute.",
      "default": "RequestResponse"
    }
  },
  "required": [
    "version",
    "operation"
  ],
  "additionalProperties": false
}

Hier ist ein Beispiel, das eine invoke Operation verwendet, deren Nutzdaten das getPost Feld aus einem GraphQL-Schema zusammen mit den Argumenten aus dem Kontext sind:

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

Das gesamte Mapping-Dokument wird als Eingabe für Ihre Lambda-Funktion übergeben, sodass das vorherige Beispiel nun wie folgt aussieht:

{
  "version": "2018-05-29",
  "operation": "Invoke",
  "payload": {
    "field": "getPost",
    "arguments": {
      "id": "postId1"
    }
  }
}

Version

Das ist allen Vorlagen für die Anforderungszuweisung gemeinsam und version definiert die Version, die die Vorlage verwendet. Der version ist erforderlich und ist ein statischer Wert:

"version": "2018-05-29"

Operation

Mit der Lambda-Datenquelle können Sie zwei Operationen im operation Feld definieren: Invoke undBatchInvoke. Die Invoke Operation teilt mit AWS AppSync , dass Sie Ihre Lambda-Funktion für jeden GraphQL-Feldresolver aufrufen sollen. BatchInvokeweist AWS AppSync an, Anfragen für das aktuelle GraphQL-Feld zu stapeln. Das Feld operation ist ein Pflichtfeld.

Denn die Vorlage für Invoke die Zuordnung aufgelöster Anfragen entspricht der Eingabe-Payload der Lambda-Funktion. Lassen Sie uns das obige Beispiel ändern:

{
  "version": "2018-05-29",
  "operation": "Invoke",
    "payload": {
      "arguments": $util.toJson($context.arguments)
    }
}

Dies wird gelöst und an die Lambda-Funktion übergeben, die etwa so aussehen könnte:

{
  "version": "2018-05-29",
  "operation": "Invoke",
    "payload": {
      "arguments": {
        "id": "postId1"
      }
    }
}

Denn BatchInvoke die Mapping-Vorlage wird auf jeden Field Resolver im Batch angewendet. Führt aus Gründen der Übersichtlichkeit alle aufgelösten payload Werte der Mapping-Vorlage zu einer Liste unter einem einzigen Objekt zusammen, das der Mapping-Vorlage entspricht. AWS AppSync Die folgende Vorlage zeigt die Zusammenfassung:

{
  "version": "2018-05-29",
  "operation": "BatchInvoke",
  "payload": $util.toJson($context)
}

Diese Vorlage ist in dem folgenden Zuweisungsdokument aufgelöst:

{
  "version": "2018-05-29",
  "operation": "BatchInvoke",
  "payload": [
    {...}, // context for batch item 1
    {...}, // context for batch item 2
    {...}  // context for batch item 3
  ]
}

Jedes Element der payload Liste entspricht einem einzelnen Batch-Element. Es wird auch erwartet, dass die Lambda-Funktion eine listenförmige Antwort zurückgibt, die der Reihenfolge der in der Anfrage gesendeten Elemente entspricht:

[
  { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 1
  { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 2
  { "data": {...}, "errorMessage": null, "errorType": null }  // result for batch item 3
]

Nutzlast

Das payload Feld ist ein Container, der verwendet wird, um wohlgeformtes JSON an die Lambda-Funktion zu übergeben. Wenn das operation Feld auf gesetzt istBatchInvoke, AWS AppSync werden die vorhandenen payload Werte in eine Liste zusammengefasst. Das Feld payload ist optional.

Art des Aufrufs

Mit der Lambda-Datenquelle können Sie zwei Aufruftypen definieren: RequestResponse und. Event Die Aufruftypen sind gleichbedeutend mit den in der Lambda-API definierten Aufruftypen. Mit dem RequestResponse AWS AppSync Aufruftyp können Sie Ihre Lambda-Funktion synchron aufrufen, um auf eine Antwort zu warten. Der Event Aufruf ermöglicht es Ihnen, Ihre Lambda-Funktion asynchron aufzurufen. Weitere Informationen darüber, wie Lambda Anfragen vom Event Aufruftyp verarbeitet, finden Sie unter Asynchroner Aufruf. Das Feld invocationType ist optional. Wenn dieses Feld nicht in der Anfrage enthalten ist, AWS AppSync wird standardmäßig der Aufruftyp verwendet. RequestResponse

Für jedes invocationType Feld entspricht die aufgelöste Anfrage der Eingabe-Payload der Lambda-Funktion. Lassen Sie uns das obige Beispiel ändern:

{
  "version": "2018-05-29",
  "operation": "Invoke",
  "invocationType": "Event"
  "payload": {
    "arguments": $util.toJson($context.arguments)
  }
}

Dies wird gelöst und an die Lambda-Funktion übergeben, die etwa so aussehen könnte:

{
  "version": "2018-05-29",
  "operation": "Invoke",
  "invocationType": "Event",
  "payload": {
    "arguments": {
      "id": "postId1"
    }
  }
}

Wenn der BatchInvoke Vorgang in Verbindung mit dem Event Aufruftypfeld verwendet wird, AWS AppSync führt er den Feldauflöser auf die oben beschriebene Weise zusammen, und die Anforderung wird als asynchrones Ereignis an Ihre Lambda-Funktion übergeben, payload wobei es sich um eine Werteliste handelt. Wir empfehlen, das Resolver-Caching für Resolver vom Event Aufruftyp zu deaktivieren, da diese bei einem Cache-Treffer nicht an Lambda gesendet würden.

Vorlage für die Zuordnung von Antworten

Wie bei anderen Datenquellen sendet Ihre Lambda-Funktion eine Antwort darauf AWS AppSync , die in einen GraphQL-Typ konvertiert werden muss.

Das Ergebnis der Lambda-Funktion wird für das context Objekt festgelegt, das über die Velocity Template Language (VTL) $context.result -Eigenschaft verfügbar ist.

Wenn die Form Ihrer Lambda-Funktionsantwort exakt der Form des GraphQL-Formats entspricht, können Sie die Antwort unter Verwendung der folgenden Zuweisungsvorlage für Antworten weiterleiten:

$util.toJson($context.result)

Es gibt keine erforderlichen Felder oder Formeinschränkungen, die auf die Zuweisungsvorlage für Antworten zutreffen. Allerdings ist GraphQL stark typisiert. Deshalb muss die Zuweisungsvorlage, auf die der Resolver angewendet wurde, dem erwarteten GraphQL-Format entsprechen.

Batch-Antwort mit Lambda-Funktion

Wenn das operation Feld auf gesetzt istBatchInvoke, wird eine Liste von Elementen AWS AppSync erwartet, die von der Lambda-Funktion zurückgegeben werden. Damit jedes Ergebnis AWS AppSync dem ursprünglichen Anforderungselement zugeordnet werden kann, muss die Antwortliste in Größe und Reihenfolge übereinstimmen. Es ist zulässig, null Elemente in der Antwortliste zu haben; sie $ctx.result wird entsprechend auf Null gesetzt.

Direkte Lambda-Resolver

Wenn Sie die Verwendung von Mapping-Vorlagen vollständig umgehen möchten, AWS AppSync können Sie eine Standardnutzlast für Ihre Lambda-Funktion und eine Standard-Lambda-Funktionsantwort für einen GraphQL-Typ bereitstellen. Sie können wählen, ob Sie eine Anforderungsvorlage, eine Antwortvorlage oder beides bereitstellen und diese entsprechend behandeln möchten. AWS AppSync

Vorlage für die direkte Zuordnung von Lambda-Anfragen

Wenn die Vorlage für die Anforderungszuweisung nicht bereitgestellt AWS AppSync wird, wird das Context Objekt als Invoke Operation direkt an Ihre Lambda-Funktion gesendet. Weitere Informationen über die Struktur des Context-Objekts finden Sie unter Kontextreferenz für Resolver-Mapping-Vorlagen.

Vorlage für die direkte Zuordnung von Lambda-Antworten

Wenn die Antwortzuordnungsvorlage nicht bereitgestellt wird, AWS AppSync führt sie beim Empfang der Antwort Ihrer Lambda-Funktion eine von zwei Aktionen aus. Wenn Sie keine Vorlage für die Anforderungszuweisung bereitgestellt haben oder wenn Sie mit der Version eine Vorlage für die Anforderungszuweisung bereitgestellt haben2018-05-29, entspricht die Antwort der folgenden Vorlage für die Antwortzuweisung:

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

Wenn Sie mit der Version eine Vorlage bereitgestellt haben2017-02-28, funktioniert die Antwortlogik genauso wie die folgende Vorlage für die Antwortzuweisung:

$util.toJson($ctx.result)

Oberflächlich betrachtet funktioniert die Umgehung von Zuordnungsvorlagen ähnlich wie die Verwendung bestimmter Zuordnungsvorlagen, wie in den vorherigen Beispielen gezeigt. Hinter den Kulissen wird die Auswertung der Mapping-Vorlagen jedoch völlig umgangen. Da der Schritt zur Template-Evaluierung umgangen wird, kann es bei Anwendungen in einigen Szenarien zu weniger Overhead und Latenz während der Antwort kommen als bei einer Lambda-Funktion mit einer Antwortzuordnungsvorlage, die evaluiert werden muss.

Benutzerdefinierte Fehlerbehandlung in Direct Lambda Resolver-Antworten

Sie können Fehlerantworten von Lambda-Funktionen, die Direct Lambda Resolver aufrufen, anpassen, indem Sie eine benutzerdefinierte Ausnahme auslösen. Das folgende Beispiel zeigt, wie eine benutzerdefinierte Ausnahme erstellt wird mit: JavaScript

class CustomException extends Error {
  constructor(message) {
    super(message);
    this.name = "CustomException";
  }
}
 
throw new CustomException("Custom message");

Wenn Ausnahmen ausgelöst werden, errorMessage sind errorType und jeweils das name und message des benutzerdefinierten Fehlers, der ausgelöst wird.

Wenn errorType jaUnauthorizedException, wird die Standardnachricht ("You are not authorized to make this call.") anstelle einer benutzerdefinierten Meldung AWS AppSync zurückgegeben.

Der folgende Ausschnitt ist ein Beispiel für eine GraphQL-Antwort, die eine benutzerdefinierte Antwort demonstriert: errorType

{
  "data": {
    "query": null
  },
  "errors": [
    {
      "path": [
        "query"
      ],
      "data": null,
      "errorType": "CustomException",
      "errorInfo": null,
      "locations": [
        {
          "line": 5,
          "column": 10,
          "sourceName": null
        }
      ],
      "message": "Custom Message"
    }
  ]
}

Direkte Lambda-Resolver: Batching aktiviert

Sie können Batching für Ihren Direct Lambda Resolver aktivieren, indem Sie den maxBatchSize auf Ihrem Resolver konfigurieren. Wenn auf einen Wert gesetzt maxBatchSize ist, der größer ist als 0 für einen Direct Lambda-Resolver, AWS AppSync sendet Anfragen stapelweise an Ihre Lambda-Funktion in Größen bis zu. maxBatchSize

Wenn maxBatchSize Sie einen Direct Lambda-Resolver 0 auf on setzen, wird die Batchverarbeitung ausgeschaltet.

Weitere Informationen zur Funktionsweise der Batchverarbeitung mit Lambda-Resolvern finden Sie unter. Anwendungsfall für Fortgeschrittene: Batching

Zuordnungsvorlage anfordern

Wenn Batching aktiviert ist und die Vorlage für die Anforderungszuweisung nicht bereitgestellt wird, AWS AppSync sendet eine Liste von Context Objekten als BatchInvoke Vorgang direkt an Ihre Lambda-Funktion.

Vorlage für die Zuordnung von Antworten

Wenn Batching aktiviert ist und die Antwortzuordnungsvorlage nicht bereitgestellt wird, entspricht die Antwortlogik der folgenden Antwortzuordnungsvorlage:

#if( $context.result && $context.result.errorMessage )
      $utils.error($context.result.errorMessage, $context.result.errorType,
      $context.result.data)
#else
      $utils.toJson($context.result.data)
#end

Die Lambda-Funktion muss eine Ergebnisliste in derselben Reihenfolge wie die Liste der gesendeten Context Objekte zurückgeben. Sie können einzelne Fehler zurückgeben, indem Sie ein errorMessage und errorType für ein bestimmtes Ergebnis angeben. Jedes Ergebnis in der Liste hat das folgende Format:

{
   "data" : { ... }, // your data
   "errorMessage" : { ... }, // optional, if included an error entry is added to the "errors" object in the AppSync response 
   "errorType" : { ... } // optional, the error type
}

Anmerkung

Andere Felder im Ergebnisobjekt werden derzeit ignoriert.

Umgang mit Fehlern von Lambda

Sie können für alle Ergebnisse einen Fehler zurückgeben, indem Sie eine Ausnahme oder einen Fehler in Ihrer Lambda-Funktion auslösen. Wenn die Payload-Anfrage oder die Antwortgröße für Ihre Batch-Anfrage zu groß ist, gibt Lambda einen Fehler zurück. In diesem Fall sollten Sie erwägen, Ihre maxBatchSize oder die Größe der Antwortnutzlast zu reduzieren.

Hinweise zur Behandlung einzelner Fehler finden Sie unterRückgabe einzelner Fehler.

Beispiele für Lambda-Funktionen

Mithilfe des folgenden Schemas können Sie einen Direct Lambda Resolver für den Post.relatedPosts Field Resolver erstellen und die Batchverarbeitung aktivieren, indem Sie die obigen Einstellungen vornehmen: maxBatchSize 0

schema {
    query: Query
    mutation: Mutation
}

type Query {
    getPost(id:ID!): Post
    allPosts: [Post]
}

type Mutation {
    addPost(id: ID!, author: String!, title: String, content: String, url: String): Post!
}

type Post {
    id: ID!
    author: String!
    title: String
    content: String
    url: String
    ups: Int
    downs: Int
    relatedPosts: [Post]
}

In der folgenden Abfrage wird die Lambda-Funktion mit Batches von Auflösungsanforderungen aufgerufen: relatedPosts

query getAllPosts {
  allPosts {
    id
    relatedPosts {
      id
    }
  }
}

Im Folgenden finden Sie eine einfache Implementierung einer Lambda-Funktion:

const posts = {
  1: {
    id: '1',
    title: 'First book',
    author: 'Author1',
    url: 'https://amazon.com/',
    content:
      'SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1',
    ups: '100',
    downs: '10',
  },
  2: {
    id: '2',
    title: 'Second book',
    author: 'Author2',
    url: 'https://amazon.com',
    content: 'SAMPLE TEXT AUTHOR 2 SAMPLE TEXT AUTHOR 2 SAMPLE TEXT',
    ups: '100',
    downs: '10',
  },
  3: { id: '3', title: 'Third book', author: 'Author3', url: null, content: null, ups: null, downs: null },
  4: {
    id: '4',
    title: 'Fourth book',
    author: 'Author4',
    url: 'https://www.amazon.com/',
    content:
      'SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4',
    ups: '1000',
    downs: '0',
  },
  5: {
    id: '5',
    title: 'Fifth book',
    author: 'Author5',
    url: 'https://www.amazon.com/',
    content: 'SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT',
    ups: '50',
    downs: '0',
  },
}

const relatedPosts = {
  1: [posts['4']],
  2: [posts['3'], posts['5']],
  3: [posts['2'], posts['1']],
  4: [posts['2'], posts['1']],
  5: [],
}
exports.handler = async (event) => {
  console.log('event ->', event)
  // retrieve the ID of each post
  const ids = event.map((context) => context.source.id)
  // fetch the related posts for each post id
  const related = ids.map((id) => relatedPosts[id])

  // return the related posts; or an error if none were found
  return related.map((r) => {
    if (r.length > 0) {
      return { data: r }
    } else {
      return { data: null, errorMessage: 'Not found', errorType: 'ERROR' }
    }
  })
}