Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Fusión en APIs AWS AppSync

A medida que el uso de GraphQL se expande dentro de una organización, pueden surgir compensaciones entre la velocidad de desarrollo API ease-of-use y API la velocidad de desarrollo. Por un lado, las organizaciones adoptan AWS AppSync GraphQL para simplificar el desarrollo de aplicaciones al ofrecer a los desarrolladores una flexibilidad API que pueden utilizar para acceder, manipular y combinar de forma segura los datos de uno o más dominios de datos con una sola llamada a la red. Por otro lado, los equipos de una organización que son responsables de los diferentes dominios de datos combinados en un único API punto final de GraphQL pueden querer tener la capacidad de crear, administrar e implementar API actualizaciones independientes unas de otras para aumentar sus velocidades de desarrollo.

Para resolver esta tensión, la APIs función AWS AppSync Merged permite a los equipos de diferentes dominios de datos crear e implementar de forma independiente AWS AppSync APIs (por ejemplo, esquemas de GraphQL, resolutores, fuentes de datos y funciones), que luego se pueden combinar en una sola combinación. API Esto permite a las organizaciones mantener un sistema multidominio y fácil de usar para los distintos equiposAPI, lo que contribuye a que puedan realizar actualizaciones API de forma rápida e independiente. API

Con MergedAPIs, las organizaciones pueden importar los recursos de varias fuentes independientes AWS AppSync APIs a un único API punto final de AWS AppSync Merged. Para ello, AWS AppSync permite crear una lista de fuentes AWS AppSync fuente yAPIs, a continuación, combinar todos los metadatos asociados a la fuente, APIs incluidos el esquema, los tipos, las fuentes de datos, los resolutores y las funciones, en una nueva combinación. AWS AppSync API

Durante las fusiones, existe la posibilidad de que se produzca un conflicto de fusión debido a inconsistencias en el contenido de los API datos de origen, como conflictos en la nomenclatura de los tipos al combinar varios esquemas. En los casos de uso sencillos en los que no haya APIs conflictos entre las definiciones de la fuente, no es necesario modificar los esquemas de la fuente. API El Merged resultante API simplemente importa todos los tipos, resolutores, fuentes de datos y funciones de la fuente original. AWS AppSync APIs Para los casos de uso complejos en los que surjan conflictos, los usuarios o equipos deberán resolver los conflictos por diversos medios. AWS AppSync proporciona a los usuarios varias herramientas y ejemplos que pueden reducir los conflictos de fusión.

Las fusiones posteriores que se configuren en AWS AppSync propagarán los cambios realizados en la fuente APIs a la combinación asociada. API

Fusión y federación APIs

Existen muchas soluciones y patrones en la comunidad de GraphQL para combinar esquemas de GraphQL y permitir la colaboración en equipo a través de un gráfico compartido. AWS AppSync Para la composición de los esquemas, Merged APIs adopta un enfoque basado en el tiempo de creación, en el que APIs las fuentes se combinan para formar un sistema Merged independiente. API Un enfoque alternativo consiste en colocar un router en tiempo de ejecución en varias fuentes APIs o subgráficos. En este enfoque, el router recibe una solicitud, hace referencia a un esquema combinado que mantiene como metadatos, crea un plan de solicitudes y, a continuación, distribuye los elementos de la solicitud entre sus subgráficos o servidores subyacentes. La siguiente tabla compara el API enfoque de tiempo de compilación AWS AppSync combinado con los enfoques de tiempo de ejecución y basados en enrutadores para la composición del esquema de GraphQL:

* AWS AppSync La combinación solo se APIs puede asociar a la AWS AppSync fuenteAPIs. Si necesita soporte para la composición de esquemas entre gráficos AWS AppSync y sin AWS AppSync subgráficos, puede conectar uno o más AWS AppSync GraphQL y/o Merged a una solución basada en APIs enrutadores. Por ejemplo, consulte el blog de referencia para añadir AWS AppSync APIs como subgráfico utilizando una arquitectura basada en enrutadores con Apollo Federation v2: Apollo GraphQL Federation with. AWS AppSync

Resolución de conflictos combinada API

En caso de un conflicto de fusión, AWS AppSync proporciona a los usuarios varias herramientas y ejemplos para ayudar a solucionar los problemas.

Directivas de API esquema combinadas

AWS AppSync ha introducido varias directivas de GraphQL que se pueden utilizar para reducir o resolver conflictos entre fuentes: APIs

Para mostrar el esquema de utilidades que proporcionan las directivas, observe el siguiente ejemplo:

En este ejemplo, supongamos que queremos fusionar dos fuentesAPIs. Tenemos dos esquemas que crean y recuperan publicaciones (p. ej., publicaciones en la sección de comentarios o en las redes sociales). Suponiendo que los tipos y los campos sean muy similares, la probabilidad de que surjan conflictos durante una operación de fusión es muy elevada. Los fragmentos siguientes muestran los tipos y campos de cada esquema.

El primer archivo, denominado Source1.graphql, es un esquema de GraphQL que permite al usuario crear Posts utilizando la mutación putPost. Cada Post contiene un título y un ID. El ID se utiliza para hacer referencia al User, o a la información del autor de la publicación (correo electrónico y dirección), y al Message, o la carga útil (contenido). El tipo de User se anota con la etiqueta @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
}

El segundo archivo, llamado Source2.graphql, es un esquema GraphQL con funciones muy similares a las de Source1.graphQL. Sin embargo, tenga en cuenta que los campos de cada tipo son diferentes. Al fusionar estos dos esquemas, se producirán conflictos de fusión debido a estas diferencias.

Observe también que Source2.graphql también contiene varias directivas para reducir estos conflictos. El tipo Post tiene anotada una etiqueta @hidden para ocultarse durante la operación de fusión. El tipo Message tiene anotada la etiqueta @renamed para cambiar el nombre del tipo a ChatMessage en caso de conflicto de nomenclatura con otro 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")
}

Cuando se produzca la fusión, el resultado generará el archivo 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
}

En la fusión ocurrieron varias cosas:

También puede ocurrir que no se agreguen directivas a un tipo con conflictos. En este caso, el tipo fusionado incluirá la unión de todos los campos de todas las definiciones de origen de ese tipo. Por ejemplo, observe el siguiente caso:

Este esquema, denominado Source1.graphql, permite crear y recuperar Posts. La configuración es similar a la del ejemplo anterior, pero con menos información.

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

Este esquema, denominado Source2.graphql, permite crear y recuperar Reviews (p. ej., valoraciones de películas o reseñas de restaurantes). Las Reviews están asociadas a la Post con el mismo valor de ID. En conjunto, contienen el título, el ID de la publicación y el mensaje de carga útil de la publicación de la reseña completa.

Al fusionarse, habrá un conflicto entre los dos tipos Post. Como no hay anotaciones para resolver este problema, se lleva a cabo, de manera predeterminada, una operación de unión de los tipos en conflicto.

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

Cuando se produzca la fusión, el resultado generará el archivo 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
}

En la fusión ocurrieron varias cosas:

Administración de solucionadores en tipos compartidos

En el ejemplo anterior, consideremos el caso en el que Source1.graphql ha configurado un solucionador de unidades en Query.getPost, que utiliza un origen de datos de DynamoDB denominado PostDatasource. Este solucionador devolverá el id y el title de un tipo Post. Ahora, consideremos que Source2.graphql ha configurado un solucionador de canalización en Post.reviews que ejecuta dos funciones. Function1 tiene un origen de datos None adjunto para realizar comprobaciones de autorización personalizadas. Function2 tiene un origen de datos de DynamoDB adjunto para consultar la tabla reviews.

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

Cuando un cliente ejecuta la consulta anterior en el API punto final Merged, el AWS AppSync servicio ejecuta primero la unidad de resolución for Query.getPost fromSource1, que llama a DynamoDB PostDatasource y devuelve los datos de DynamoDB. A continuación, ejecuta el solucionador de canalizaciones de Post.reviews, en el cual Function1 ejecuta una lógica de autorización personalizada y Function2 devuelve las revisiones en función del id encontrado en $context.source. El servicio procesa la solicitud como una sola ejecución de GraphQL, y esta solicitud sencilla requiere un único token de solicitud.

Gestión de conflictos de solucionadores en tipos compartidos

Veamos el caso siguiente, en el que también implementamos un solucionador en Query.getPost para proporcionar varios campos a la vez además del solucionador de campo en Source2. Source1.graphql sería parecido a esto:

# This snippet represents a file called Source1.graphql

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

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

Source2.graphql sería parecido a esto:

# This snippet represents a file called Source2.graphql

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

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

Si se intenta combinar estos dos esquemas, se generará un error de combinación, ya que AWS AppSync APIs Merged no permite adjuntar varios resolutores de origen al mismo campo. Para resolver este conflicto, puede implementar un patrón de solucionador de campo que obligaría a Source2.graphql a agregar un tipo diferente que defina los campos del tipo Post que le pertenecen. En el siguiente ejemplo, agregamos un tipo denominado PostInfo, que contiene los campos de contenido y de autor que resolverá Source2.graphql. Source1.graphql implementará el solucionador asociado a Query.getPost, mientras que Source2.graphql asociará ahora un solucionador a Post.postInfo para garantizar que todos los datos se puedan recuperar correctamente:

type Post  {
  id: ID!
  postInfo: PostInfo
}

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

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

Si bien la resolución de este tipo de conflictos requiere que se reescriban los API esquemas fuente y, posiblemente, que los clientes cambien sus consultas, la ventaja de este enfoque es que la propiedad de los solucionadores fusionados queda clara entre los equipos de origen.

Configuración de esquemas

Dos partes son responsables de configurar los esquemas para crear una combinación: API

Como el esquema API de Merged se crea a partir de los esquemas de la fuente asociadaAPIs, es de solo lectura. Esto significa que los cambios en el esquema deben iniciarse en tu fuenteAPIs. En la AWS AppSync consola, puede cambiar entre el esquema fusionado y los esquemas individuales de la fuente APIs incluidos en el esquema fusionado API mediante la lista desplegable situada encima de la ventana del esquema.

Configuración de modos de autorización

Hay varios modos de autorización disponibles para proteger su Merged. API Para obtener más información sobre los modos de autorización AWS AppSync, consulte Autorización y autenticación.

Los siguientes modos de autorización están disponibles para su uso con MergedAPIs:

Los modos de autorización de una fusión API los configura el API propietario de la fusión. En el momento de una operación de fusión, la unidad fusionada API debe incluir el modo de autorización principal configurado en una fuente, API ya sea como su propio modo de autorización principal o como modo de autorización secundario. De lo contrario, será incompatible, la operación de fusión producirá un error y se generará un conflicto. Cuando se utilizan directivas de autenticación múltiple en el origenAPIs, el proceso de fusión puede combinar automáticamente estas directivas en el punto final unificado. En el caso de que el modo de autorización principal de la fuente API no coincida con el modo de autorización principal de la fuente fusionadaAPI, añadirá automáticamente estas directivas de autenticación para garantizar que el modo de autorización de los tipos de la fuente sea coherente. API

Configuración de roles de ejecución

Al crear un FusionadoAPI, es necesario definir un rol de servicio. Una función de AWS servicio es una función de AWS Identity and Access Management (IAM) que utilizan los AWS servicios para realizar tareas en su nombre.

En este contexto, es necesario que Merged ejecute resolutores que accedan API a los datos de las fuentes de datos configuradas en su fuenteAPIs. El rol de servicio necesario para ello es el permisomergedApiExecutionRole, y debe tener acceso explícito para ejecutar las solicitudes en la fuente APIs incluida en la fusión API mediante el appsync:SourceGraphQL IAM permiso. Durante la ejecución de una solicitud de GraphQL, el AWS AppSync servicio asumirá este rol de servicio y lo autorizará a realizar la appsync:SourceGraphQL acción.

AWS AppSync permite permitir o denegar este permiso en campos específicos de nivel superior de la solicitud, como el modo de IAM autorización. IAM APIs En el non-top-level caso de los campos, AWS AppSync requiere que definas el permiso en la API ARN propia fuente. Para restringir el acceso a non-top-level campos específicos de MergedAPI, recomendamos implementar una lógica personalizada en su Lambda u ocultar los API campos de origen de Merged API mediante la directiva @hidden. Si quieres permitir que el rol realice todas las operaciones de datos dentro de una fuenteAPI, puedes añadir la política que se indica a continuación. Tenga en cuenta que la primera entrada de recursos permite el acceso a todos los campos de nivel superior y la segunda incluye las resoluciones secundarias que autorizan en el propio API recurso de origen:

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

Si quiere limitar el acceso únicamente a un campo de nivel superior específico, puede usar una política como esta:

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

También puedes usar el asistente de API creación de la AWS AppSync consola para generar un rol de servicio que permita a tu equipo combinado acceder API a los recursos configurados en el origen APIs que se encuentran en la misma cuenta que el usuario fusionado. API En el caso de que su fuente no APIs esté en la misma cuenta que la fusionadaAPI, primero debe compartir los recursos mediante AWS Resource Access Manager (AWS RAM).

Configuración de varias cuentas combinadas APIs mediante AWS RAM

Al crear una cuenta fusionadaAPI, si lo desea, puede asociar la fuente APIs de otras cuentas que se hayan compartido mediante AWS Resource Access Manager (AWS RAM). AWS RAM le ayuda a compartir sus recursos de forma segura entre AWS cuentas, dentro de su organización o unidades organizativas (OUs) y con IAM roles y usuarios.

AWS AppSync se integra con AWS RAM para permitir la configuración y el acceso a la fuente APIs en varias cuentas desde una sola cuenta MergedAPI. AWS RAM permite crear un recurso compartido o un contenedor de recursos y los conjuntos de permisos que se compartirán para cada uno de ellos. Puede añadir recursos AWS AppSync APIs a un recurso compartido en AWS RAM. Dentro de un recurso compartido, AWS AppSync proporciona tres conjuntos de permisos diferentes que se pueden asociar a una AWS AppSync API entradaRAM:

AWS AppSync también admite los permisos gestionados por el cliente. Si uno de los permisos AWS administrados proporcionados no funciona, puedes crear tu propio permiso administrado por el cliente. Los permisos gestionados por el cliente son permisos gestionados que usted crea y mantiene especificando con precisión qué acciones se pueden realizar y en qué condiciones con los recursos que se comparten. AWS RAM AWS AppSync le permite elegir entre las siguientes acciones al crear su propio permiso:

Una vez que haya compartido correctamente una fuente API o se haya fusionado API AWS RAM y, si es necesario, se haya aceptado la invitación a compartir el recurso, estará visible en la AWS AppSync consola cuando cree o actualice API las asociaciones de fuentes en la fuente fusionadaAPI. También puedes hacer una lista de todas las AWS AppSync APIs que se han compartido AWS RAM con tu cuenta, independientemente del permiso establecido, llamando a la ListGraphqlApis operación proporcionada por el propietario AWS AppSync y utilizando el filtro OTHER_ACCOUNTS propietario.

Fusión

Administración de fusiones

El objetivo de APIs Merged es facilitar la colaboración en equipo en un AWS AppSync punto final unificado. Los equipos pueden desarrollar de forma independiente su propio GraphQL de origen aislado APIs en el backend, mientras que el AWS AppSync servicio gestiona la integración de los recursos en el único API punto final fusionado para reducir la fricción en la colaboración y reducir los plazos de desarrollo.

Fusiones automáticas

La fuente APIs asociada a la fuente AWS AppSync fusionada se API puede configurar para que se fusione automáticamente (se fusione automáticamente) en la fusionada API después de realizar cualquier cambio en la fuenteAPI. Esto garantiza que los cambios de la fuente siempre API se propaguen al API punto final de Merged en segundo plano. Cualquier cambio en el API esquema de origen se actualizará en el Fusionado siempre API que no introduzca un conflicto de fusión con una definición existente en el FusionadoAPI. Si la actualización de la fuente API actualiza una resolución, una fuente de datos o una función, también se actualizará el recurso importado. Cuando se introduce un nuevo conflicto que no se puede resolver automáticamente (se resuelve automáticamente), la actualización del API esquema combinado se rechaza debido a un conflicto no admitido durante la operación de combinación. El mensaje de error está disponible en la consola para cada API asociación de fuentes cuyo estado sea. MERGE_FAILED También puede inspeccionar el mensaje de error llamando a la GetSourceApiAssociation operación de una API asociación de fuentes determinada utilizando AWS SDK o usando una AWS CLI similar, de la siguiente manera:

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

Esto generará un resultado con el formato siguiente:

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

Fusiones manuales

La configuración por defecto de una fuente API es una combinación manual. Para combinar cualquier cambio que se haya producido en la fuente APIs desde la última actualización de la fuente API fusionada, el API propietario de la fuente puede invocar una fusión manual desde la AWS AppSync consola o mediante la StartSchemaMerge operación disponible en AWS SDK y AWS CLI.

Soporte adicional para Merged APIs

Configuración de suscripciones

A diferencia de los enfoques basados en enrutadores para la composición de esquemas de GraphQL, AWS AppSync Merged APIs proporciona soporte integrado para las suscripciones de GraphQL. Todas las operaciones de suscripción definidas en tu fuente asociada se APIs fusionarán automáticamente y funcionarán en tu Merged sin modificaciones. API Para obtener más información sobre cómo se AWS AppSync admiten las suscripciones mediante una WebSockets conexión sin servidor, consulte Datos en tiempo real.

Configuración de la observabilidad

AWS AppSync APIsLos fusionados proporcionan registros, monitoreo y métricas integrados a través de Amazon CloudWatch. AWS AppSync también proporciona soporte integrado para el rastreo mediante AWS X-Ray.

Configuración de dominios personalizados

AWS AppSync Merged APIs proporciona soporte integrado para el uso de dominios personalizados con los puntos de conexión GraphQL y Real-Time de MergedAPI.

Configuración del almacenamiento en caché

AWS AppSync Merged APIs ofrece soporte integrado para almacenar en caché, de forma opcional, las respuestas a nivel de solicitud o a nivel de resolución, así como para la compresión de respuestas. Para obtener más información, consulte Almacenamiento en caché y compresión.

Configuración privada APIs

AWS AppSync Merged APIs proporciona compatibilidad integrada con Private, APIs que limita el acceso a los puntos finales GraphQL y Real-time de Merged al tráfico que se origina en los VPCpuntos finales que puede configurar. API

Configuración de reglas de firewall

AWS AppSync Merged APIs ofrece soporte integrado para AWS WAF, lo que le permite proteger sus aplicaciones APIs mediante la definición de reglas de firewall para aplicaciones web.

Configuración de registros de auditoría

AWS AppSync Merged APIs ofrece soporte integrado para AWS CloudTrail, lo que le permite configurar y gestionar los registros de auditoría.

APILimitaciones combinadas

Al desarrollar MergedAPIs, ten en cuenta las siguientes reglas:

Creando Merged APIs

Para crear una fusión API en la consola