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.
Zusammengeführte APIs
Wenn der Einsatz von GraphQL innerhalb eines Unternehmens zunimmt, können Kompromisse zwischen API ease-of-use - und API-Entwicklungsgeschwindigkeit entstehen. Einerseits setzen AWS AppSync Unternehmen GraphQL ein, um die Anwendungsentwicklung zu vereinfachen, indem sie Entwicklern eine flexible API zur Verfügung stellen, mit der sie mit einem einzigen Netzwerkaufruf sicher auf Daten aus einer oder mehreren Datendomänen zugreifen, diese bearbeiten und kombinieren können. Andererseits möchten Teams innerhalb einer Organisation, die für die verschiedenen Datendomänen verantwortlich sind, die zu einem einzigen GraphQL-API-Endpunkt zusammengefasst sind, möglicherweise die Möglichkeit haben, API-Updates unabhängig voneinander zu erstellen, zu verwalten und bereitzustellen, um ihre Entwicklungsgeschwindigkeit zu erhöhen.
Um dieses Problem zu lösen, ermöglicht die Funktion „AWS AppSyncZusammengeführte APIs“ es Teams aus verschiedenen Datendomänen, unabhängig voneinander AWS AppSync APIs (z. B. GraphQL-Schemas, Resolver, Datenquellen und Funktionen) zu erstellen und bereitzustellen, die dann zu einer einzigen, zusammengeführten API kombiniert werden können. Dies gibt Unternehmen die Möglichkeit, eine einfach zu verwendende, domänenübergreifende API zu verwalten, und bietet den verschiedenen Teams, die an dieser API beteiligt sind, die Möglichkeit, API-Updates schnell und unabhängig voneinander vorzunehmen.
![](images/merged-api-workflow.png)
Mithilfe zusammengeführter APIs können Unternehmen die Ressourcen mehrerer, unabhängiger AWS AppSync Quell-APIs in einen einzigen AWS AppSync zusammengeführten API-Endpunkt importieren. Zu diesem Zweck AWS AppSync können Sie eine Liste von Quell-APIs erstellen und anschließend alle mit den AWS AppSync Quell-APIs verknüpften Metadaten, einschließlich Schema, Typen, Datenquellen, Resolver und Funktionen, zu einer neuen AWS AppSync zusammengeführten API zusammenführen.
Bei Zusammenführungen besteht die Möglichkeit, dass aufgrund von Inkonsistenzen im Inhalt der Quell-API-Daten, wie z. B. Typbenennungskonflikte beim Kombinieren mehrerer Schemas, ein Zusammenführungskonflikt auftritt. Für einfache Anwendungsfälle, in denen keine Definitionen in den Quell-APIs miteinander in Konflikt stehen, müssen die Quell-API-Schemas nicht geändert werden. Die daraus resultierende zusammengeführte API importiert einfach alle Typen, Resolver, Datenquellen und Funktionen aus den ursprünglichen AWS AppSync Quell-APIs. Bei komplexen Anwendungsfällen, in denen Konflikte auftreten, müssen die Benutzer/Teams die Konflikte auf verschiedene Weise lösen. AWS AppSyncstellt Benutzern verschiedene Tools und Beispiele zur Verfügung, mit denen Zusammenführungskonflikte reduziert werden können.
Nachfolgende Zusammenführungen, die in konfiguriert sind, übertragen Änderungen, AWS AppSync die an den Quell-APIs vorgenommen wurden, auf die zugehörige zusammengeführte API.
Zusammengeführte APIs und Federation
In der GraphQL-Community gibt es viele Lösungen und Muster, um GraphQL-Schemas zu kombinieren und die Teamzusammenarbeit über einen gemeinsamen Graphen zu ermöglichen. AWS AppSync Zusammengeführte APIs verfolgen bei der Schemazusammenstellung einen Build-Time-Ansatz, bei dem Quell-APIs zu einer separaten, zusammengeführten API kombiniert werden. Ein alternativer Ansatz besteht darin, einen Runtime-Router über mehrere Quell-APIs oder Untergraphen zu verteilen. Bei diesem Ansatz empfängt der Router eine Anfrage, verweist auf ein kombiniertes Schema, das er als Metadaten verwaltet, erstellt einen Anforderungsplan und verteilt dann die Anforderungselemente auf die zugrunde liegenden Subgraphen/Server. In der folgenden Tabelle wird der Build-Time-Ansatz der AWS AppSync zusammengeführten API mit routerbasierten Laufzeitansätzen für die GraphQL-Schemakomposition verglichen:
Feature | AppSync Merged API | Router-based solutions |
Sub-graphs managed independently | Yes | Yes |
Sub-graphs addressable independently | Yes | Yes |
Automated schema composition | Yes | Yes |
Automated conflict detection | Yes | Yes |
Conflict resolution via schema directives | Yes | Yes |
Supported sub-graph servers | AWS AppSync* | Varies |
Network complexity | Single, merged API means no extra network hops. | Multi-layer architecture requires query planning and delegation, sub-query parsing and serialization/deserialization, and reference resolvers in sub-graphs to perform joins. |
Observability support | Built-in monitoring, logging, and tracing. A single, Merged API server means simplified debugging. | Build-your-own observability across router and all associated sub-graph servers. Complex debugging across distributed system. |
Authorization support | Built in support for multiple authorization modes. | Build-your-own authorization rules. |
Cross account security | Built-in support for cross-AWS cloud account associations. | Build-your-own security model. |
Subscriptions support | Yes | No |
* Zusammengeführte APIs können nur Quell-APIs zugeordnet werden. AWS AppSync AWS AppSync Wenn Sie Unterstützung für die Schemakomposition zwischen AWS AppSync und ohne AWS AppSync Unterdiagramme benötigen, können Sie eine oder mehrere AWS AppSync GraphQL- und/oder Merged-APIs zu einer routerbasierten Lösung verbinden. Sehen Sie sich beispielsweise den Referenz-Blog zum Hinzufügen von AWS AppSync APIs als Unterdiagramm unter Verwendung einer routerbasierten Architektur mit Apollo Federation v2: Apollo GraphQL
Themen
- Konfliktlösung zusammengeführter APIs
- Schemas konfigurieren
- Autorisierungsmodi konfigurieren
- Konfiguration von Ausführungsrollen
- Konfiguration kontenübergreifender zusammengeführter APIs mit AWS RAM
- Zusammenführen
- Zusätzliche Unterstützung für zusammengeführte APIs
- Einschränkungen zusammengeführter APIs
- Zusammengeführte APIs erstellen
Konfliktlösung zusammengeführter APIs
AWS AppSyncStellt Benutzern im Falle eines Zusammenführungskonflikts verschiedene Tools und Beispiele zur Verfügung, um die Probleme zu beheben.
Richtlinien für zusammengeführte API-Schemas
AWS AppSynchat mehrere GraphQL-Direktiven eingeführt, die verwendet werden können, um Konflikte zwischen Quell-APIs zu reduzieren oder zu lösen:
-
@canonical: Diese Direktive legt den Vorrang von Typen/Feldern mit ähnlichen Namen und Daten fest. Wenn zwei oder mehr Quell-APIs denselben GraphQL-Typ oder dasselbe GraphQL-Feld haben, kann eine der APIs ihren Typ oder ihr Feld als kanonisch annotieren, was bei der Zusammenführung priorisiert wird. Widersprüchliche Typen/Felder, die in anderen Quell-APIs nicht mit dieser Direktive annotiert sind, werden beim Zusammenführen ignoriert.
-
@hidden: Diese Direktive kapselt bestimmte Typen/Felder, um sie aus dem Zusammenführungsprozess zu entfernen. Teams möchten möglicherweise bestimmte Typen oder Operationen in der Quell-API entfernen oder verbergen, sodass nur interne Kunden auf bestimmte typisierte Daten zugreifen können. Wenn diese Direktive angehängt ist, werden Typen oder Felder nicht in der zusammengeführten API zusammengeführt.
-
@renamed: Diese Direktive ändert die Namen von Typen/Feldern, um Namenskonflikte zu reduzieren. Es gibt Situationen, in denen verschiedene APIs denselben Typ oder Feldnamen haben. Sie müssen jedoch alle im zusammengeführten Schema verfügbar sein. Eine einfache Möglichkeit, sie alle in die zusammengeführte API aufzunehmen, besteht darin, das Feld in etwas Ähnliches, aber anderes umzubenennen.
Sehen Sie sich das folgende Beispiel an, um zu zeigen, was die Utility-Schema-Direktiven bieten:
Nehmen wir in diesem Beispiel an, dass wir zwei Quell-APIs zusammenführen möchten. Wir erhalten zwei Schemas, mit denen Beiträge erstellt und abgerufen werden können (z. B. Kommentarbereich oder Beiträge in sozialen Medien). Unter der Annahme, dass sich die Typen und Felder sehr ähnlich sind, besteht bei einer Zusammenführung ein hohes Konfliktpotenzial. Die folgenden Ausschnitte zeigen die Typen und Felder der einzelnen Schemas.
Die erste Datei mit dem Namen Source1.graphQL ist ein GraphQL-Schema, das es einem Benutzer ermöglicht, mithilfe der Mutation zu erstellenPosts
. putPost
Jede Post
enthält einen Titel und eine ID. Die ID wird verwendetUser
, um auf die Informationen des Posters (E-Mail und Adresse) und auf die Message
Payload (Inhalt) zu verweisen. Der User
Typ ist mit dem @canonical -Tag annotiert.
# This snippet represents a file called Source1.graphql type Mutation { putPost(id: ID!, title: String!): Post } type Post { id: ID! title: String! } type Message { id: ID! content: String } type User @canonical { id: ID! email: String! address: String! } type Query { singlePost(id: ID!): Post getMessage(id: ID!): Message }
Die zweite Datei namens Source2.graphql ist ein GraphQL-Schema, das sehr ähnliche Dinge tut wie Source1.graphql. Beachten Sie jedoch, dass die Felder der einzelnen Typen unterschiedlich sind. Beim Zusammenführen dieser beiden Schemas kommt es aufgrund dieser Unterschiede zu Zusammenführungskonflikten.
Beachten Sie auch, dass Source2.graphql auch mehrere Direktiven enthält, um diese Konflikte zu reduzieren. Der Post
Typ ist mit einem @hidden -Tag versehen, um sich während des Zusammenführungsvorgangs selbst zu verschleiern. Der Message
Typ ist mit dem @renamed -Tag versehen, in den der Typname geändert werden kann, falls es zu ChatMessage
einem Namenskonflikt mit einem anderen Typ kommt. Message
# This snippet represents a file called Source2.graphql type Post @hidden { id: ID! title: String! internalSecret: String! } type Message @renamed(to: "ChatMessage") { id: ID! chatId: ID! from: User! to: User! } # Stub user so that we can link the canonical definition from Source1 type User { id: ID! } type Query { getPost(id: ID!): Post getMessage(id: ID!): Message @renamed(to: "getChatMessage") }
Wenn die Zusammenführung erfolgt, ergibt das Ergebnis die folgende MergedSchema.graphql
Datei:
# This snippet represents a file called MergedSchema.graphql type Mutation { putPost(id: ID!, title: String!): Post } # Post from Source2 was hidden so only uses the Source1 definition. type Post { id: ID! title: String! } # Renamed from Message to resolve the conflict type ChatMessage { id: ID! chatId: ID! from: User! to: User! } type Message { id: ID! content: String } # Canonical definition from Source1 type User { id: ID! email: String! address: String! } type Query { singlePost(id: ID!): Post getMessage(id: ID!): Message # Renamed from getMessage getChatMessage(id: ID!): ChatMessage }
Bei der Zusammenführung sind mehrere Dinge passiert:
-
Der
User
Typ aus Source1.graphql hatte aufgrund der @canonical -Annotation Vorrang vor demUser
von Source2.graphql. -
Der
Message
Typ aus Source1.graphql wurde in die Zusammenführung aufgenommen. DerMessage
von Source2.graphql hatte jedoch einen Namenskonflikt. Aufgrund seiner @renamed -Annotation wurde es ebenfalls in die Zusammenführung aufgenommen, jedoch mit dem alternativen Namen.ChatMessage
-
Der
Post
Typ aus Source1.graphql war enthalten, derPost
Typ aus Source2.graphql jedoch nicht. Normalerweise würde es bei diesem Typ einen Konflikt geben, aber da derPost
Typ aus Source2.graphql eine @hidden -Annotation hatte, wurden seine Daten verschleiert und nicht in die Zusammenführung aufgenommen. Dies führte zu keinen Konflikten. -
Der
Query
Typ wurde aktualisiert, sodass er den Inhalt beider Dateien enthält. EineGetMessage
Abfrage wurde jedochGetChatMessage
aufgrund der Direktive in umbenannt. Dadurch wurde der Namenskonflikt zwischen den beiden Abfragen mit demselben Namen behoben.
Es kommt auch vor, dass einem widersprüchlichen Typ keine Direktiven hinzugefügt wurden. Hier beinhaltet der zusammengeführte Typ die Vereinigung aller Felder aus allen Quelldefinitionen dieses Typs. Sehen Sie sich dazu das folgende Beispiel an:
Dieses Schema, Source1.graphQL genannt, ermöglicht das Erstellen und Abrufen. Posts
Die Konfiguration ähnelt dem vorherigen Beispiel, enthält jedoch weniger Informationen.
# This snippet represents a file called Source1.graphql type Mutation { putPost(id: ID!, title: String!): Post } type Post { id: ID! title: String! } type Query { getPost(id: ID!): Post }
Dieses Schema mit dem Namen Source2.graphql ermöglicht das Erstellen und Abrufen Reviews
(z. B. Filmbewertungen oder Restaurantkritiken). Reviews
sind mit demselben ID-Wert Post
verknüpft. Zusammen enthalten sie den Titel, die Beitrags-ID und die Nutzdatennachricht des vollständigen Bewertungsbeitrags.
Beim Zusammenführen wird es zu einem Konflikt zwischen den beiden Post
Typen kommen. Da es keine Anmerkungen zur Lösung dieses Problems gibt, besteht das Standardverhalten darin, eine Vereinigung der widersprüchlichen Typen durchzuführen.
# This snippet represents a file called Source2.graphql type Mutation { putReview(id: ID!, postId: ID!, comment: String!): Review } type Post { id: ID! reviews: [Review] } type Review { id: ID! postId: ID! comment: String! } type Query { getReview(id: ID!): Review }
Wenn die Zusammenführung erfolgt, ergibt das Ergebnis die folgende Datei: MergedSchema.graphql
# This snippet represents a file called MergedSchema.graphql type Mutation { putReview(id: ID!, postId: ID!, comment: String!): Review putPost(id: ID!, title: String!): Post } type Post { id: ID! title: String! reviews: [Review] } type Review { id: ID! postId: ID! comment: String! } type Query { getPost(id: ID!): Post getReview(id: ID!): Review }
Bei der Zusammenführung sind mehrere Dinge passiert:
-
Der
Mutation
Typ hatte keine Konflikte und wurde zusammengeführt. -
Die
Post
Typfelder wurden im Rahmen einer Union-Operation kombiniert. Beachten Sie, wie die Vereinigung der beiden zu einem Singleid
title
, einem und einem Single führtereviews
. -
Der
Review
Typ hatte keine Konflikte und wurde zusammengeführt. -
Der
Query
Typ hatte keine Konflikte und wurde zusammengeführt.
Verwaltung von Resolvern auf gemeinsam genutzten Typen
Stellen Sie sich im obigen Beispiel den Fall vor, dass Source1.graphql einen Unit-Resolver konfiguriert hatQuery.getPost
, der eine DynamoDB-Datenquelle mit dem Namen verwendet. PostDatasource
Dieser Resolver gibt das und eines Typs zurück. id
title
Post
Stellen Sie sich nun vor, dass Source2.graphql einen Pipeline-Resolver konfiguriert hatPost.reviews
, auf dem zwei Funktionen ausgeführt werden. Function1
hat eine None
Datenquelle angehängt, um benutzerdefinierte Autorisierungsprüfungen durchzuführen. Function2
hat eine DynamoDB-Datenquelle angehängt, um die reviews
Tabelle abzufragen.
query GetPostQuery { getPost(id: "1") { id, title, reviews } }
Wenn die obige Abfrage von einem Client für den Merged API-Endpunkt ausgeführt wird, führt der AWS AppSync Dienst zunächst den Unit-Resolver für Query.getPost
from ausSource1
, der DynamoDB aufruft PostDatasource
und die Daten von DynamoDB zurückgibt. Anschließend führt er den Post.reviews
Pipeline-Resolver aus, der Function1
eine benutzerdefinierte Autorisierungslogik ausführt und die Bewertungen Function2
zurückgibt, die in gefunden wurden. id
$context.source
Der Dienst verarbeitet die Anfrage als einen einzigen GraphQL-Lauf, und für diese einfache Anfrage ist nur ein einziges Anforderungstoken erforderlich.
Verwaltung von Lösungskonflikten bei gemeinsam genutzten Typen
Stellen Sie sich den folgenden Fall vor, Query.getPost
in dem wir auch einen Resolver auf implementieren, um mehrere Felder gleichzeitig bereitzustellen, die über den Feld-Resolver in hinausgehen. Source2
Source1.graphql könnte so aussehen:
# This snippet represents a file called Source1.graphql type Post { id: ID! title: String! date: AWSDateTime! } type Query { getPost(id: ID!): Post }
Source2.graphql könnte so aussehen:
# This snippet represents a file called Source2.graphql type Post { id: ID! content: String! contentHash: String! author: String! } type Query { getPost(id: ID!): Post }
Der Versuch, diese beiden Schemas zusammenzuführen, führt zu einem Zusammenführungsfehler, da AWS AppSync zusammengeführte APIs nicht zulassen, dass mehrere Quell-Resolver an dasselbe Feld angehängt werden. Um diesen Konflikt zu lösen, können Sie ein Feldauflösungsmuster implementieren, bei dem Source2.graphql einen separaten Typ hinzufügen müsste, der die Felder, die es besitzt, von dem Typ definiert. Post
Im folgenden Beispiel fügen wir einen Typ namens hinzu, der die Inhalts- und Autorenfelder enthältPostInfo
, die von Source2.graphql aufgelöst werden. Source1.graphql implementiert den an angehängten ResolverQuery.getPost
, wohingegen Source2.graphql nun einen Resolver anhängt, um sicherzustellen, dass alle Daten erfolgreich abgerufen werden können: Post.postInfo
type Post { id: ID! postInfo: PostInfo } type PostInfo { content: String! contentHash: String! author: String! } type Query { getPost(id: ID!): Post }
Die Lösung eines solchen Konflikts erfordert zwar, dass die Quell-API-Schemas neu geschrieben werden und die Clients möglicherweise ihre Abfragen ändern müssen. Der Vorteil dieses Ansatzes besteht jedoch darin, dass die Eigentümer der zusammengeführten Resolver für alle Quellteams weiterhin klar sind.
Schemas konfigurieren
Zwei Parteien sind für die Konfiguration der Schemas verantwortlich, um eine zusammengeführte API zu erstellen:
-
Besitzer zusammengeführter APIs — Besitzer zusammengeführter APIs müssen die Autorisierungslogik der zusammengeführten API und erweiterte Einstellungen wie Protokollierung, Tracing, Caching und WAF-Unterstützung konfigurieren.
-
Eigentümer der assoziierten Quell-API — Besitzer assoziierter APIs müssen die Schemas, Resolver und Datenquellen konfigurieren, aus denen die zusammengeführte API besteht.
Da das Schema Ihrer zusammengeführten API aus den Schemas Ihrer verknüpften Quell-APIs erstellt wird, ist es schreibgeschützt. Das bedeutet, dass Änderungen am Schema in Ihren Quell-APIs initiiert werden müssen. In der AWS AppSync Konsole können Sie mithilfe der Dropdownliste über dem Schemafenster zwischen Ihrem zusammengeführten Schema und den einzelnen Schemas der in Ihrer zusammengeführten API enthaltenen Quell-APIs wechseln.
Autorisierungsmodi konfigurieren
Zum Schutz Ihrer zusammengeführten API stehen mehrere Autorisierungsmodi zur Verfügung. Weitere Informationen zu den Autorisierungsmodi finden Sie unter Autorisierung und Authentifizierung. AWS AppSync
Die folgenden Autorisierungsmodi stehen für die Verwendung mit zusammengeführten APIs zur Verfügung:
-
API-Schlüssel: Die einfachste Autorisierungsstrategie. Alle Anfragen müssen einen API-Schlüssel unter dem
x-api-key
Anforderungsheader enthalten. Abgelaufene API-Schlüssel werden 60 Tage nach dem Ablaufdatum aufbewahrt. -
AWSIdentity and Access Management (IAM): Die AWS IAM-Autorisierungsstrategie autorisiert alle Anfragen, die mit Sigv4 signiert sind.
-
Amazon Cognito Cognito-Benutzerpools: Autorisieren Sie Ihre Benutzer über Amazon Cognito Cognito-Benutzerpools, um eine genauere Kontrolle zu erhalten.
-
AWSLambda Authorizers: Eine serverlose Funktion, mit der Sie den Zugriff auf Ihre API mithilfe benutzerdefinierter Logik authentifizieren und autorisieren können. AWS AppSync
-
OpenID Connect: Dieser Autorisierungstyp erzwingt OpenID Connect-Token (OIDC), die von einem OIDC-kompatiblen Dienst bereitgestellt werden. Ihre Anwendung kann Benutzer und Berechtigungen nutzen, die von Ihrem OIDC-Anbieter zur Kontrolle des Zugriffs definiert wurden.
Die Autorisierungsmodi einer zusammengeführten API werden vom Eigentümer der zusammengeführten API konfiguriert. Zum Zeitpunkt eines Zusammenführungsvorgangs muss die zusammengeführte API den auf einer Quell-API konfigurierten primären Autorisierungsmodus entweder als eigenen primären Autorisierungsmodus oder als sekundären Autorisierungsmodus enthalten. Andernfalls ist sie inkompatibel und der Zusammenführungsvorgang schlägt mit einem Konflikt fehl. Wenn Multi-Auth-Direktiven in den Quell-APIs verwendet werden, kann der Zusammenführungsprozess diese Direktiven automatisch mit dem vereinheitlichten Endpunkt zusammenführen. Falls der primäre Autorisierungsmodus der Quell-API nicht mit dem primären Autorisierungsmodus der zusammengeführten API übereinstimmt, werden diese Authentifizierungsdirektiven automatisch hinzugefügt, um sicherzustellen, dass der Autorisierungsmodus für die Typen in der Quell-API konsistent ist.
Konfiguration von Ausführungsrollen
Wenn Sie eine zusammengeführte API erstellen, müssen Sie eine Servicerolle definieren. Eine AWS Servicerolle ist eine AWS Identity and Access Management (IAM) -Rolle, die von AWS Diensten verwendet wird, um Aufgaben in Ihrem Namen auszuführen.
In diesem Zusammenhang ist es erforderlich, dass Ihre zusammengeführte API Resolver ausführt, die auf Daten aus den in Ihren Quell-APIs konfigurierten Datenquellen zugreifen. Die dafür erforderliche Servicerolle ist diemergedApiExecutionRole
, und sie muss über die appsync:SourceGraphQL
IAM-Berechtigung expliziten Zugriff haben, um Anfragen an Quell-APIs auszuführen, die in Ihrer zusammengeführten API enthalten sind. Während der Ausführung einer GraphQL-Anfrage übernimmt der AWS AppSync Dienst diese Dienstrolle und autorisiert die Rolle, die Aktion auszuführen. appsync:SourceGraphQL
AWS AppSyncunterstützt das Zulassen oder Verweigern dieser Berechtigung für bestimmte Felder der obersten Ebene innerhalb der Anfrage, z. B. wie der IAM-Autorisierungsmodus für IAM-APIs funktioniert. Für non-top-level Felder AWS AppSync müssen Sie die Berechtigung für den Quell-API-ARN selbst definieren. Um den Zugriff auf bestimmte non-top-level Felder in der Merged-API einzuschränken, empfehlen wir, eine benutzerdefinierte Logik in Ihrem Lambda zu implementieren oder die Quell-API-Felder mithilfe der @hidden -Direktive vor der Merged-API auszublenden. Wenn Sie der Rolle erlauben möchten, alle Datenoperationen innerhalb einer Quell-API auszuführen, können Sie die folgende Richtlinie hinzufügen. Beachten Sie, dass der erste Ressourceneintrag den Zugriff auf alle Felder der obersten Ebene ermöglicht und der zweite Eintrag untergeordnete Resolver abdeckt, die für die Quell-API-Ressource selbst autorisieren:
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "appsync:SourceGraphQL"], "Resource": [ "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId/*", "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId"] }] }
Wenn Sie den Zugriff nur auf ein bestimmtes Feld der obersten Ebene beschränken möchten, können Sie eine Richtlinie wie die folgende verwenden:
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "appsync:SourceGraphQL"], "Resource": [ "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId/types/Query/fields/<Field-1>", "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId"] }] }
Sie können auch den AWS AppSync Konsolen-API-Erstellungsassistenten verwenden, um eine Servicerolle zu generieren, damit Ihre zusammengeführte API auf Ressourcen zugreifen kann, die in Quell-APIs konfiguriert sind, die sich in demselben Konto wie Ihre zusammengeführte API befinden. Falls sich Ihre Quell-APIs nicht in demselben Konto wie Ihre zusammengeführte API befinden, müssen Sie zunächst Ihre Ressourcen mithilfe von AWS Resource Access Manager (AWS RAM) gemeinsam nutzen.
Konfiguration kontenübergreifender zusammengeführter APIs mit AWS RAM
Wenn Sie eine zusammengeführte API erstellen, können Sie optional Quell-APIs von anderen Konten zuordnen, die über AWS Resource Access Manager (AWS RAM) gemeinsam genutzt wurden. AWS RAMhilft Ihnen dabei, Ihre Ressourcen sicher zwischen AWS Konten, innerhalb Ihrer Organisation oder Organisationseinheiten (OUs) und mit IAM-Rollen und -Benutzern gemeinsam zu nutzen.
AWS AppSyncintegriert sich AWS RAM in, um die Konfiguration und den Zugriff auf Quell-APIs für mehrere Konten von einer einzigen zusammengeführten API aus zu unterstützen. AWS RAMermöglicht es Ihnen, eine gemeinsame Ressourcennutzung oder einen Container mit Ressourcen und den Berechtigungssätzen zu erstellen, die für jede Ressource gemeinsam genutzt werden. Sie können AWS AppSync APIs zu einer Ressourcenfreigabe in hinzufügenAWS RAM. AWS AppSyncStellt innerhalb einer Ressourcenfreigabe drei verschiedene Berechtigungssätze bereit, die einer AWS AppSync API im RAM zugeordnet werden können:
-
AWSRAMPermissionAppSyncSourceApiOperationAccess
: Der Standard-Berechtigungssatz, der hinzugefügt wird, wenn eine AWS AppSync API gemeinsam genutzt wird, AWS RAM sofern keine andere Berechtigung angegeben ist. Dieser Berechtigungssatz wird für die gemeinsame Nutzung einer AWS AppSync Quell-API mit einem Besitzer einer zusammengeführten API verwendet. Dieser Berechtigungssatz umfasst die Berechtigung fürappsync:AssociateMergedGraphqlApi
die Quell-API sowie die für den Zugriff auf die Quell-API-Ressourcen zur Laufzeit erforderlichenappsync:SourceGraphQL
Berechtigungen. -
AWSRAMPermissionAppSyncMergedApiOperationAccess
: Dieser Berechtigungssatz sollte konfiguriert werden, wenn eine zusammengeführte API mit einem Eigentümer der Quell-API geteilt wird. Dieser Berechtigungssatz gibt der Quell-API die Möglichkeit, die zusammengeführte API zu konfigurieren, einschließlich der Möglichkeit, alle Quell-APIs, die dem Zielprinzipal gehören, der zusammengeführten API zuzuordnen und die Quell-API-Verknüpfungen der zusammengeführten API zu lesen und zu aktualisieren. -
AWSRAMPermissionAppSyncAllowSourceGraphQLAccess
: Dieser Berechtigungssatz ermöglicht die Verwendung derappsync:SourceGraphQL
Berechtigung mit einer AWS AppSync API. Es ist für die gemeinsame Nutzung einer Quell-API mit einem Eigentümer einer zusammengeführten API vorgesehen. Im Gegensatz zum Standardberechtigungssatz für den Zugriff auf Quell-API-Operationen umfasst dieser Berechtigungssatz nur die Laufzeitberechtigungappsync:SourceGraphQL
. Wenn sich ein Benutzer dafür entscheidet, den Zugriff auf den Vorgang der zusammengeführten API mit einem Eigentümer der Quell-API zu teilen, muss er diese Berechtigung auch von der Quell-API an den Eigentümer der zusammengeführten API weitergeben, um über den Endpunkt der zusammengeführten API Laufzeitzugriff zu erhalten.
AWS AppSyncunterstützt auch vom Kunden verwaltete Berechtigungen. Wenn eine der bereitgestellten AWS verwalteten Berechtigungen nicht funktioniert, können Sie Ihre eigene vom Kunden verwaltete Berechtigung erstellen. Kundenverwaltete Berechtigungen sind verwaltete Berechtigungen, die Sie erstellen und verwalten, indem Sie genau angeben, welche Aktionen unter welchen Bedingungen mit gemeinsam genutzten Ressourcen ausgeführt werden können. AWS RAM AWS AppSyncermöglicht es Ihnen, bei der Erstellung Ihrer eigenen Berechtigungen aus den folgenden Aktionen zu wählen:
-
appsync:AssociateSourceGraphqlApi
-
appsync:AssociateMergedGraphqlApi
-
appsync:GetSourceApiAssociation
-
appsync:UpdateSourceApiAssociation
-
appsync:StartSchemaMerge
-
appsync:ListTypesByAssociation
-
appsync:SourceGraphQL
Sobald Sie eine Quell-API oder eine zusammengeführte API ordnungsgemäß freigegeben haben AWS RAM und, falls erforderlich, die Einladung zur gemeinsamen Nutzung von Ressourcen akzeptiert wurde, wird sie in der AWS AppSync Konsole angezeigt, wenn Sie die Quell-API-Verknüpfungen auf Ihrer zusammengeführten API erstellen oder aktualisieren. Sie können auch alle AWS AppSync APIs auflisten, die AWS RAM mit Ihrem Konto geteilt wurden, unabhängig vom jeweiligen Berechtigungssatz, indem Sie den von Ihnen bereitgestellten ListGraphqlApis
Vorgang aufrufen AWS AppSync und den OTHER_ACCOUNTS
Besitzerfilter verwenden.
Anmerkung
Für das Teilen über AWS RAM muss der Anrufer AWS RAM die Erlaubnis haben, die appsync:PutResourcePolicy
Aktion auf jeder API auszuführen, die gemeinsam genutzt wird.
Zusammenführen
Zusammenführungen verwalten
Zusammengeführte APIs sollen die Teamzusammenarbeit auf einem einheitlichen AWS AppSync Endpunkt unterstützen. Teams können unabhängig voneinander ihre eigenen isolierten GraphQL-Quell-APIs im Backend entwickeln, während der AWS AppSync Service die Integration der Ressourcen in den einzigen zusammengeführten API-Endpunkt verwaltet, um die Reibung bei der Zusammenarbeit zu verringern und die Entwicklungsvorlaufzeiten zu verkürzen.
Automatische Zusammenführungen
Quell-APIs, die mit Ihrer AWS AppSync zusammengeführten API verknüpft sind, können so konfiguriert werden, dass sie automatisch mit der zusammengeführten API zusammengeführt (Auto-Merge) werden, nachdem Änderungen an der Quell-API vorgenommen wurden. Dadurch wird sichergestellt, dass die Änderungen von der Quell-API immer im Hintergrund an den Endpunkt der zusammengeführten API weitergegeben werden. Jede Änderung am Quell-API-Schema wird in der zusammengeführten API aktualisiert, sofern dadurch kein Mergekonflikt mit einer vorhandenen Definition in der zusammengeführten API entsteht. Wenn das Update in der Quell-API einen Resolver, eine Datenquelle oder eine Funktion aktualisiert, wird auch die importierte Ressource aktualisiert. Wenn ein neuer Konflikt eingeführt wird, der nicht automatisch gelöst werden kann (automatisch gelöst), wird die Aktualisierung des Schemas der zusammengeführten API aufgrund eines nicht unterstützten Konflikts während des Zusammenführungsvorgangs abgelehnt. Die Fehlermeldung ist in der Konsole für jede Quell-API-Zuordnung verfügbar, die den Status hat. MERGE_FAILED
Sie können die Fehlermeldung auch überprüfen, indem Sie den GetSourceApiAssociation
Vorgang für eine bestimmte Quell-API-Zuordnung mit dem AWS SDK oder der AWS CLI wie folgt aufrufen:
aws appsync get-source-api-association --merged-api-identifier <Merged API ARN> --association-id <SourceApiAssociation id>
Dies führt zu einem Ergebnis im folgenden Format:
{ "sourceApiAssociation": { "associationId": "<association id>", "associationArn": "<association arn>", "sourceApiId": "<source api id>", "sourceApiArn": "<source api arn>", "mergedApiArn": "<merged api arn>", "mergedApiId": "<merged api id>", "sourceApiAssociationConfig": { "mergeType": "MANUAL_MERGE" }, "sourceApiAssociationStatus": "MERGE_FAILED", "sourceApiAssociationStatusDetail": "Unable to resolve conflict on object with name title: Merging is not supported for fields with different types." } }
Manuelle Zusammenführungen
Die Standardeinstellung für eine Quell-API ist eine manuelle Zusammenführung. Um alle Änderungen zusammenzuführen, die seit der letzten Aktualisierung der zusammengeführten API an den Quell-APIs vorgenommen wurden, kann der Eigentümer der Quell-API eine manuelle Zusammenführung von der AWS AppSync Konsole aus oder über den im AWS SDK und der AWS CLI verfügbaren StartSchemaMerge
Vorgang aufrufen.
Zusätzliche Unterstützung für zusammengeführte APIs
Konfiguration von Abonnements
Im Gegensatz zu routerbasierten Ansätzen zur GraphQL-Schemakomposition bieten AWS AppSync zusammengeführte APIs integrierte Unterstützung für GraphQL-Abonnements. Alle Abonnementvorgänge, die in Ihren zugehörigen Quell-APIs definiert sind, werden automatisch zusammengeführt und funktionieren in Ihrer zusammengeführten API ohne Änderung. Weitere Informationen darüber, wie Abonnements über serverlose WebSockets Verbindungen AWS AppSync unterstützt werden, finden Sie unter Echtzeitdaten.
Beobachtbarkeit konfigurieren
AWS AppSyncZusammengeführte APIs bieten integrierte Protokollierung, Überwachung und Metriken über Amazon CloudWatch. AWS AppSyncbietet auch integrierte Unterstützung für die Rückverfolgung über AWS X-Ray.
Konfiguration benutzerdefinierter Domänen
AWS AppSyncZusammengeführte APIs bieten integrierte Unterstützung für die Verwendung benutzerdefinierter Domains mit den GraphQL- und Echtzeit-Endpunkten Ihrer zusammengeführten API.
Caching konfigurieren
AWS AppSyncZusammengeführte APIs bieten integrierte Unterstützung für das optionale Zwischenspeichern von Antworten auf Anfrage- und/oder Resolverebene sowie für die Antwortkomprimierung. Weitere Informationen finden Sie unter Caching und Komprimierung.
Private APIs konfigurieren
AWS AppSyncZusammengeführte APIs bieten integrierte Unterstützung für private APIs, die den Zugriff auf die GraphQL- und Echtzeit-Endpunkte Ihrer zusammengeführten API auf den Datenverkehr beschränken, der von VPC-Endpunkten stammt, die Sie konfigurieren können.
Konfiguration von Firewall-Regeln
AWS AppSyncZusammengeführte APIs bieten integrierte Unterstützung fürAWS WAF, sodass Sie Ihre APIs schützen können, indem Sie Firewall-Regeln für Webanwendungen definieren.
Konfiguration von Audit-Logs
AWS AppSyncZusammengeführte APIs bieten integrierte Unterstützung für AWS CloudTrail, sodass Sie Auditprotokolle konfigurieren und verwalten können.
Einschränkungen zusammengeführter APIs
Beachten Sie bei der Entwicklung zusammengeführter APIs die folgenden Regeln:
-
Eine zusammengeführte API kann keine Quell-API für eine andere zusammengeführte API sein.
-
Eine Quell-API kann nicht mehr als einer zusammengeführten API zugeordnet werden.
-
Die Standardgrößenbeschränkung für ein zusammengeführtes API-Schemadokument beträgt 10 MB.
-
Die Standardanzahl von Quell-APIs, die einer zusammengeführten API zugeordnet werden können, ist 10. Sie können jedoch eine Erhöhung des Limits beantragen, wenn Sie mehr als 10 Quell-APIs in Ihrer zusammengeführten API benötigen.
Zusammengeführte APIs erstellen
Um eine zusammengeführte API in der Konsole zu erstellen
-
Melden Sie sich bei der AWS Management Console an und öffnen Sie die AWS AppSync-Konsole
. -
Wählen Sie im Dashboard Create API aus.
-
-
Wählen Sie „Zusammengeführte API“ und anschließend „Weiter“.
-
Geben Sie auf der Seite „API-Details angeben“ die folgenden Informationen ein:
-
Geben Sie unter API-Details die folgenden Informationen ein:
-
Geben Sie den API-Namen Ihrer zusammengeführten API an. Dieses Feld ist eine Möglichkeit, Ihre GraphQL-API zu kennzeichnen, um sie bequem von anderen GraphQL-APIs zu unterscheiden.
-
Geben Sie die Kontaktdaten an. Dieses Feld ist optional und fügt der GraphQL-API einen Namen oder eine Gruppe hinzu. Es ist nicht mit anderen Ressourcen verknüpft oder wird von diesen generiert und funktioniert ähnlich wie das API-Namensfeld.
-
-
Unter Servicerolle müssen Sie Ihrer zusammengeführten API eine IAM-Ausführungsrolle zuordnen, damit Sie Ihre Ressourcen zur Laufzeit sicher importieren und verwenden AWS AppSync können. Sie können wählen, ob Sie eine neue Servicerolle erstellen und verwenden möchten, sodass Sie angeben können, welche Richtlinien und Ressourcen verwendet AWS AppSync werden sollen. Sie können auch eine vorhandene IAM-Rolle importieren, indem Sie „Bestehende Servicerolle verwenden“ und dann die Rolle aus der Dropdownliste auswählen.
-
Unter Private API-Konfiguration können Sie festlegen, ob private API-Funktionen aktiviert werden sollen. Beachten Sie, dass diese Auswahl nach der Erstellung der zusammengeführten API nicht geändert werden kann. Weitere Informationen zu privaten APIs finden Sie unter AWS AppSyncPrivate APIs verwenden.
Wählen Sie Weiter, wenn Sie fertig sind.
-
-
Als Nächstes müssen Sie die GraphQL-APIs hinzufügen, die als Grundlage für Ihre zusammengeführte API verwendet werden. Geben Sie auf der Seite Quell-APIs auswählen die folgenden Informationen ein:
-
Wählen Sie in der Tabelle „APIs“ in Ihrer AWS Kontentabelle die Option Quell-APIs hinzufügen aus. In der Liste der GraphQL-APIs enthält jeder Eintrag die folgenden Daten:
-
Name: Das API-Namensfeld der GraphQL-API.
-
API-ID: Der eindeutige ID-Wert der GraphQL-API.
-
Primärer Authentifizierungsmodus: Der Standardautorisierungsmodus für die GraphQL-API. Weitere Informationen zu den Autorisierungsmodi finden Sie unter Autorisierung und Authentifizierung. AWS AppSync
-
Zusätzlicher Authentifizierungsmodus: Die sekundären Autorisierungsmodi, die in der GraphQL-API konfiguriert wurden.
-
Wählen Sie die APIs aus, die Sie in der zusammengeführten API verwenden möchten, indem Sie das Kontrollkästchen neben dem Feld Name der API aktivieren. Wählen Sie anschließend Quell-APIs hinzufügen. Die ausgewählten GraphQL-APIs werden in den APIs aus Ihrer AWS Kontentabelle angezeigt.
-
-
Wählen Sie in der Tabelle „APIs aus anderen AWS Konten“ die Option Quell-APIs hinzufügen aus. Die GraphQL-APIs in dieser Liste stammen von anderen Konten, die ihre Ressourcen über AWS Resource Access Manager (AWS RAM) mit Ihren teilen. Das Verfahren zur Auswahl von GraphQL-APIs in dieser Tabelle ist derselbe wie im vorherigen Abschnitt. Weitere Informationen zur gemeinsamen Nutzung von Ressourcen finden Sie AWS RAM unter Was istAWS Resource Access Manager? .
Wählen Sie Weiter, wenn Sie fertig sind.
-
Fügen Sie Ihren primären Authentifizierungsmodus hinzu. Weitere Informationen finden Sie unter Autorisierung und Authentifizierung. Wählen Sie Weiter.
-
Überprüfe deine Eingaben und wähle dann Create API.
-