Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Fusione APIs AWS AppSync

Man mano che l'uso di GraphQL si espande all'interno di un'organizzazione, possono sorgere compromessi tra API ease-of-use velocità di sviluppo e compromessi. API Da un lato, le organizzazioni adottano AWS AppSync GraphQL per semplificare lo sviluppo di applicazioni offrendo agli sviluppatori una soluzione flessibile API da utilizzare per accedere, manipolare e combinare in modo sicuro i dati di uno o più domini di dati con una singola chiamata di rete. D'altra parte, i team all'interno di un'organizzazione responsabili dei diversi domini di dati combinati in un unico endpoint API GraphQL potrebbero desiderare la possibilità di creare, gestire e API distribuire aggiornamenti indipendentemente l'uno dall'altro per aumentare le proprie velocità di sviluppo.

Per risolvere questa tensione, la APIs funzionalità AWS AppSync Merged consente ai team di diversi domini di dati di creare e implementare in modo indipendente AWS AppSync APIs (ad esempio schemi GraphQL, resolver, fonti di dati e funzioni), che possono quindi essere combinati in un unico, unito. API Ciò offre alle organizzazioni la possibilità di mantenere un sistema semplice da usare, interdominio API e un modo per i diversi team che contribuiscono a ciò di apportare aggiornamenti in modo rapido e indipendente. API API

Utilizzando MergedAPIs, le organizzazioni possono importare le risorse di più fonti indipendenti AWS AppSync APIs in un unico endpoint AWS AppSync unitoAPI. A tale scopo, AWS AppSync consente di creare un elenco di fonti di origine e quindi unire tutti i metadati associati alla AWS AppSync fonteAPIs, APIs inclusi schema, tipi, origini dati, resolver e funzioni, in una nuova unità. AWS AppSync API

Durante le unioni, esiste la possibilità che si verifichi un conflitto di unione a causa di incongruenze nel contenuto dei dati di origineAPI, ad esempio conflitti di denominazione dei tipi quando si combinano più schemi. Per casi d'uso semplici in cui non vi sono definizioni nell'origine in APIs conflitto, non è necessario modificare gli schemi di origine. API Il Merged risultante importa API semplicemente tutti i tipi, i resolver, le fonti di dati e le funzioni dalla fonte originale. AWS AppSync APIs Per casi d'uso complessi in cui sorgono conflitti, gli utenti/team dovranno risolvere i conflitti con vari mezzi. AWS AppSync fornisce agli utenti diversi strumenti ed esempi in grado di ridurre i conflitti di fusione.

Le fusioni successive configurate in AWS AppSync propagheranno le modifiche apportate nell'origine APIs alla fusione associata. API

Unione e federazione APIs

Esistono molte soluzioni e modelli nella community GraphQL per combinare schemi GraphQL e consentire la collaborazione in team attraverso un grafico condiviso. AWS AppSync Le operazioni di fusione APIs adottano un approccio alla composizione dello schema in fase di compilazione, in cui i sorgenti APIs vengono combinati in un formato separato, denominato Merged. API Un approccio alternativo consiste nel sovrapporre un router in fase di esecuzione su più sorgenti APIs o sottografi. In questo approccio, il router riceve una richiesta, fa riferimento a uno schema combinato che mantiene come metadati, crea un piano di richiesta e quindi distribuisce gli elementi della richiesta tra i sottografi/server sottostanti. La tabella seguente confronta l'approccio Merged API build-time con gli approcci di runtime basati sul router alla composizione dello AWS AppSync schema GraphQL:

* L' AWS AppSync unione APIs può essere associata AWS AppSync solo alla fonte. APIs Se hai bisogno di supporto per la composizione dello schema tra AWS AppSync e non AWS AppSync sotto grafici, puoi connettere uno o più GraphQL e/o Merged a una AWS AppSync soluzione basata su router. APIs Ad esempio, consulta il blog di riferimento per l'aggiunta AWS AppSync APIs come sottografo utilizzando un'architettura basata su router con Apollo Federation v2: Apollo GraphQL Federation with. AWS AppSync

Risoluzione unificata dei conflitti API

In caso di conflitto di fusione, AWS AppSync fornisce agli utenti diversi strumenti ed esempi per aiutare a risolvere il/i problema/i.

Direttive dello schema unite API

AWS AppSync ha introdotto diverse direttive GraphQL che possono essere utilizzate per ridurre o risolvere i conflitti tra i sorgenti: APIs

Per mostrare lo schema di utilità fornito dalle direttive, consideriamo il seguente esempio:

In questo esempio, supponiamo di voler unire due sorgenti. APIs Ci vengono forniti due schemi per creare e recuperare i post (ad esempio, sezione commenti o post sui social media). Supponendo che i tipi e i campi siano molto simili, c'è un'alta probabilità di conflitto durante un'operazione di unione. I frammenti seguenti mostrano i tipi e i campi di ogni schema.

Il primo file, chiamato Source1.graphQL, è uno schema GraphQL che consente a un utente di creare utilizzando la mutazione. Posts putPost Ciascuno Post contiene un titolo e un ID. L'ID viene utilizzato per fare riferimento alle informazioni del poster (e-mail e indirizzo) e alMessage, o al payload (contenuto). User Il User tipo è annotato con il tag @canonical.

# 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
}

Il secondo file, chiamato Source2.graphQL, è uno schema GraphQL che fa cose molto simili a Source1.graphQL. Tuttavia, notate che i campi di ogni tipo sono diversi. Quando si uniscono questi due schemi, si verificheranno conflitti di unione dovuti a queste differenze.

Nota anche come Source2.graphQL contenga anche diverse direttive per ridurre questi conflitti. Il Post tipo è annotato con un tag @hidden per offuscarsi durante l'operazione di unione. Il Message tipo è annotato con il tag @renamed per modificare il nome del tipo ChatMessage in caso di conflitto di denominazione con un altro tipo. 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")
}

Quando si verifica l'unione, il risultato produrrà il file: MergedSchema.graphql

# 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
}

Durante l'unione si sono verificate diverse cose:

C'è anche il caso in cui nessuna direttiva venga aggiunta a un tipo in conflitto. Qui, il tipo unito includerà l'unione di tutti i campi di tutte le definizioni di origine di quel tipo. Ad esempio, si consideri il seguente esempio:

Questo schema, chiamato Source1.graphQL, consente la creazione e il recupero. Posts La configurazione è simile all'esempio precedente, ma con meno informazioni.

# 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
}

Questo schema, chiamato Source2.GraphQL, consente di creare e recuperare Reviews (ad esempio, la valutazione dei film o le recensioni dei ristoranti). Reviewssono associati allo stesso valore ID. Post Insieme, contengono il titolo, l'ID del post e il messaggio di payload del post completo della recensione.

Durante la fusione, si verificherà un conflitto tra i due Post tipi. Poiché non esistono annotazioni per risolvere questo problema, il comportamento predefinito consiste nell'eseguire un'operazione di unione sui tipi in conflitto.

# 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
}

Quando si verifica l'unione, il risultato produrrà il file: 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
}

Durante l'unione si sono verificate diverse cose:

Gestione dei resolver su tipi condivisi

Nell'esempio precedente, considera il caso in cui Source1.GraphQL ha configurato un resolver di unità su, Query.getPost che utilizza un'origine dati DynamoDB denominata. PostDatasource Questo resolver restituirà un tipo e. id title Post Consideriamo ora che Source2.graphQL ha configurato un resolver di pipeline su, che esegue due funzioni. Post.reviews Function1ha una fonte di None dati allegata per eseguire controlli di autorizzazione personalizzati. Function2ha un'origine dati DynamoDB allegata per interrogare la tabella. reviews

query GetPostQuery {
    getPost(id: "1") {
        id,
        title,
        reviews
    }
}

Quando la query precedente viene eseguita da un client sull'APIendpoint Merged, il AWS AppSync servizio esegue innanzitutto il resolver di unità per Query.getPost fromSource1, che chiama PostDatasource e restituisce i dati da DynamoDB. Quindi, esegue il resolver della Post.reviews pipeline in cui Function1 esegue una logica di autorizzazione personalizzata e restituisce le recensioni fornite. Function2 id $context.source Il servizio elabora la richiesta come una singola esecuzione GraphQL e questa semplice richiesta richiederà solo un singolo token di richiesta.

Gestione dei conflitti dei resolver su tipi condivisi

Considera il seguente caso in cui implementiamo anche un resolver on per fornire più campi contemporaneamente oltre al resolver di campo Query.getPost in cui è inserito. Source2 Source1.graphQL può assomigliare a questo:

# This snippet represents a file called Source1.graphql

type Post  {
    id: ID!
    title: String!
    date: AWSDateTime!
}

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

Source2.graphQL può assomigliare a questo:

# This snippet represents a file called Source2.graphql

type Post  {
  id: ID!
  content: String!
  contentHash: String! 
  author: String! 
}

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

Il tentativo di unire questi due schemi genererà un errore di unione perché Merged APIs non consente di collegare più AWS AppSync resolver di origine allo stesso campo. Per risolvere questo conflitto, puoi implementare un pattern di risoluzione dei campi che richieda a Source2.GraphQL di aggiungere un tipo separato che definirà i campi di sua proprietà rispetto al tipo. Post Nell'esempio seguente, aggiungiamo un tipo chiamatoPostInfo, che contiene i campi content e author che verranno risolti da Source2.graphQL. Source1.graphQL implementerà il resolver collegato aQuery.getPost, mentre Source2.graphQL ora collegherà un resolver per garantire che tutti i dati possano essere recuperati con successo: Post.postInfo

type Post  {
  id: ID!
  postInfo: PostInfo
}

type PostInfo {
   content: String!
   contentHash: String!
   author: String!
}

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

Sebbene la risoluzione di tale conflitto richieda la riscrittura API degli schemi di origine e, potenzialmente, la modifica delle query da parte dei client, il vantaggio di questo approccio è che la proprietà dei resolver uniti rimane chiara a tutti i team di origine.

Configurazione degli schemi

Due parti sono responsabili della configurazione degli schemi per creare un sistema unito: API

Poiché lo schema API di Merged viene creato dagli schemi della fonte associata, è di sola lettura. APIs Ciò significa che le modifiche allo schema devono essere avviate nella fonte. APIs Nella AWS AppSync console, è possibile passare dallo schema Merged ai singoli schemi dell'origine APIs inclusi in Merged API utilizzando l'elenco a discesa sopra la finestra Schema.

Configurazione delle modalità di autorizzazione

Sono disponibili diverse modalità di autorizzazione per proteggere il tuo API Merged. Per ulteriori informazioni sulle modalità di autorizzazione in AWS AppSync, consulta Autorizzazione e autenticazione.

Le seguenti modalità di autorizzazione sono disponibili per l'uso con Merged: APIs

Le modalità di autorizzazione di una fusione API sono configurate dal proprietario dell'unione. API Al momento di un'operazione di unione, il sistema Merged API deve includere la modalità di autorizzazione principale configurata su un'origine API come modalità di autorizzazione principale propria o come modalità di autorizzazione secondaria. In caso contrario, sarà incompatibile e l'operazione di unione avrà esito negativo a causa di un conflitto. Quando si utilizzano direttive multi-auth nell'origineAPIs, il processo di fusione è in grado di unire automaticamente queste direttive nell'endpoint unificato. Nel caso in cui la modalità di autorizzazione principale dell'origine API non corrisponda alla modalità di autorizzazione principale di MergedAPI, aggiungerà automaticamente queste direttive di autenticazione per garantire che la modalità di autorizzazione per i tipi nell'origine sia coerente. API

Configurazione dei ruoli di esecuzione

Quando si crea una fusioneAPI, è necessario definire un ruolo di servizio. Un ruolo di AWS servizio è un ruolo AWS Identity and Access Management (IAM) utilizzato dai AWS servizi per eseguire attività per conto dell'utente.

In questo contesto, è necessario che Merged API esegua resolver che accedano ai dati dalle origini dati configurate nell'origine. APIs Il ruolo di servizio richiesto a tale scopo è ilmergedApiExecutionRole, e deve disporre dell'accesso esplicito all'esecuzione delle richieste sulla fonte APIs inclusa nell'unione tramite l'autorizzazione. API appsync:SourceGraphQL IAM Durante l'esecuzione di una richiesta GraphQL, il AWS AppSync servizio assumerà questo ruolo di servizio e autorizzerà il ruolo a eseguire l'azione. appsync:SourceGraphQL

AWS AppSync supporta l'autorizzazione o la negazione di questa autorizzazione su specifici campi di primo livello all'interno della richiesta, ad esempio in che modo funziona la modalità di IAM autorizzazione. IAM APIs Per non-top-level i campi, AWS AppSync richiede di definire l'autorizzazione sulla fonte API ARN stessa. Per limitare l'accesso a non-top-level campi specifici in MergedAPI, ti consigliamo di implementare una logica personalizzata all'interno di Lambda o di nascondere i campi di API origine al API Merged utilizzando la direttiva @hidden. Se desideri consentire al ruolo di eseguire tutte le operazioni sui dati all'interno di un'origineAPI, puoi aggiungere la politica seguente. Tieni presente che la prima voce di risorsa consente l'accesso a tutti i campi di primo livello e la seconda voce riguarda i resolver secondari che autorizzano la risorsa di origine stessa: API

{
    "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"] 
    }] 
}

Se desideri limitare l'accesso solo a uno specifico campo di primo livello, puoi utilizzare una politica come questa:

{
    "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"] 
    }] 
}

Puoi anche utilizzare la procedura guidata di API creazione della AWS AppSync console per generare un ruolo di servizio che consenta a Merged di accedere API alle risorse configurate nel codice sorgente APIs che si trovano nello stesso account del sistema unito. API Nel caso in cui la fonte non si APIs trovi nello stesso account dell'unioneAPI, devi prima condividere le tue AWS risorse utilizzando Resource Access Manager (AWS RAM).

Configurazione della fusione tra account tramite APIs AWS RAM

Quando crei un oggetto MergedAPI, puoi facoltativamente associare la fonte APIs di altri account che sono stati condivisi tramite AWS Resource Access Manager ()AWS RAM. AWS RAM consente di condividere le risorse in modo sicuro tra AWS account, all'interno dell'organizzazione o delle unità organizzative (OUs) e con IAM ruoli e utenti.

AWS AppSync si integra con AWS RAM per supportare la configurazione e l'accesso ai sorgenti APIs su più account da un'unica unità unita. API AWS RAM consente di creare una condivisione di risorse o un contenitore di risorse e i set di autorizzazioni che verranno condivisi per ciascuna di esse. È possibile aggiungere AWS AppSync APIs a una condivisione di risorse in AWS RAM. All'interno di una condivisione di risorse, AWS AppSync fornisce tre diversi set di autorizzazioni che possono essere associati AWS AppSync API a un inRAM:

AWS AppSync supporta anche le autorizzazioni gestite dal cliente. Quando una delle autorizzazioni AWS gestite fornite non funziona, puoi creare un'autorizzazione gestita dal cliente personalizzata. Le autorizzazioni gestite dal cliente sono autorizzazioni gestite che puoi creare e gestire specificando con precisione quali azioni possono essere eseguite in quali condizioni con risorse condivise. AWS RAM AWS AppSync consente di scegliere tra le seguenti azioni durante la creazione delle proprie autorizzazioni:

Dopo aver condiviso correttamente una fonte API o aver effettuato l'unione API AWS RAM e, se necessario, l'invito alla condivisione delle risorse è stato accettato, l'invito alla condivisione delle risorse sarà visibile nella AWS AppSync console quando si creano o si aggiornano API le associazioni di fonti nella versione API Unita. Puoi anche elencare tutto ciò AWS AppSync APIs che è stato condiviso AWS RAM con il tuo account, indipendentemente dal set di autorizzazioni, richiamando l'ListGraphqlApisoperazione fornita da AWS AppSync e utilizzando il filtro OTHER_ACCOUNTS proprietario.

Unire

Gestione delle unioni

APIsLe fusioni hanno lo scopo di supportare la collaborazione in team su un endpoint AWS AppSync unificato. I team possono far evolvere in modo indipendente la propria fonte isolata APIs GraphQL nel backend, mentre AWS AppSync il servizio gestisce l'integrazione delle risorse nel singolo endpoint API Merged al fine di ridurre l'attrito nella collaborazione e ridurre i tempi di sviluppo.

Unioni automatiche

L'origine APIs associata all'unità AWS AppSync unita API può essere configurata per l'unione automatica (unione automatica) nella fonte unita API dopo aver apportato modifiche all'origine. API Ciò garantisce che le modifiche dall'origine API vengano sempre propagate all'endpoint Merged in background. API Qualsiasi modifica nello API schema di origine verrà aggiornata nel API Merged a condizione che non introduca un conflitto di unione con una definizione esistente nel Merged. API Se l'aggiornamento nell'origine API aggiorna un resolver, un'origine dati o una funzione, verrà aggiornata anche la risorsa importata. Quando viene introdotto un nuovo conflitto che non può essere risolto automaticamente (risolto automaticamente), l'aggiornamento API dello schema unito viene rifiutato a causa di un conflitto non supportato durante l'operazione di unione. Il messaggio di errore è disponibile nella console per ogni associazione di origine con uno stato di. API MERGE_FAILED È inoltre possibile controllare il messaggio di errore chiamando l'GetSourceApiAssociationoperazione per una determinata API associazione di origine utilizzando AWS SDK o utilizzando un metodo AWS CLI simile:

aws appsync get-source-api-association --merged-api-identifier <Merged API ARN> --association-id <SourceApiAssociation id>

Ciò produrrà un risultato nel seguente formato:

{
    "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."
    }
}

Unioni manuali

L'impostazione predefinita per una sorgente API è l'unione manuale. Per unire le modifiche apportate all'origine APIs dall'ultimo aggiornamento di MergedAPI, il API proprietario della fonte può richiamare un'unione manuale dalla AWS AppSync console o tramite l'StartSchemaMergeoperazione disponibile in and. AWS SDK AWS CLI

Supporto aggiuntivo per Merged APIs

Configurazione degli abbonamenti

A differenza degli approcci basati su router alla composizione dello schema GraphQL, AWS AppSync Merged fornisce supporto APIs integrato per gli abbonamenti GraphQL. Tutte le operazioni di sottoscrizione definite nella fonte associata verranno automaticamente unite e APIs funzioneranno in Merged senza modifiche. API Per ulteriori informazioni su come AWS AppSync supporta gli abbonamenti tramite WebSockets connessione serverless, consulta Dati in tempo reale.

Configurazione dell'osservabilità

AWS AppSync Merged APIs fornisce registrazione, monitoraggio e metriche integrate tramite Amazon. CloudWatch AWS AppSync fornisce anche supporto integrato per il tracciamento tramite. AWS X-Ray

Configurazione di domini personalizzati

AWS AppSync Merged APIs fornisce supporto integrato per l'utilizzo di domini personalizzati con gli endpoint API GraphQL e Real-time di Merged.

Configurazione della memorizzazione nella cache

AWS AppSync Merged APIs fornisce supporto integrato per la memorizzazione opzionale nella cache delle risposte a livello di richiesta e/o a livello di resolver, nonché per la compressione delle risposte. Per ulteriori informazioni, consulta Caching e compressione.

Configurazione privata APIs

AWS AppSync Merged APIs fornisce un supporto integrato per Private APIs che limita l'accesso agli endpoint API GraphQL e Real-time di Merged al traffico proveniente dagli VPC endpoint che puoi configurare.

Configurazione delle regole del firewall

AWS AppSync Merged APIs fornisce un supporto integrato per AWS WAF, che consente di proteggere le applicazioni Web APIs definendo regole di firewall.

Configurazione dei log di controllo

AWS AppSync Merged APIs fornisce supporto integrato per AWS CloudTrail, che consente di configurare e gestire i registri di controllo.

Limitazioni unite API

Durante lo sviluppo di MergedAPIs, prendi nota delle seguenti regole:

Creazione di Merged APIs

Per creare un oggetto Merged API nella console