API fusionadas - AWS AppSync
API fusionadas y federaciónResolución de conflictos de la API fusionadaConfiguración de esquemasConfiguración de modos de autorizaciónConfiguración de roles de ejecuciónConfiguración de API fusionadas entre cuentas mediante AWS RAMFusiónAsistencia adicional para las API fusionadasLimitaciones de las API fusionadasCreación de API fusionadas

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.

API fusionadas

A medida que se generaliza el uso de GraphQL en una organización, la facilidad de uso de las API puede afectar a su velocidad de desarrollo y viceversa. Por un lado, las organizaciones adoptan AWS AppSync y GraphQL para simplificar el desarrollo de aplicaciones, puesto que se ofrece a los desarrolladores una API flexible que les permite acceder a los datos de uno o más dominios de datos, así como manipularlos y combinarlos. Todo ello de forma segura y con una sola llamada a la red. Por otro lado, puede que los equipos de una organización que se encargan de los diferentes dominios de datos fusionados en un único punto de conexión de la API de GraphQL quieran tener la capacidad para crear, administrar e implementar actualizaciones de API independientes entre sí a fin de acelerar su desarrollo.

Para resolver esta tensión, la característica de API fusionadas de AWS AppSync permite a los equipos de dominios de datos diferentes crear e implementar API de AWS AppSync de forma independiente (p. ej., esquemas, solucionadores, orígenes de datos y funciones de GraphQL), que luego se pueden combinar en una misma API fusionada. De este modo, las organizaciones pueden mantener una API multidominio fácil de usar y los diferentes equipos que colaboran en esa API pueden aplicar actualizaciones de la API de forma rápida e independiente.

Con las API fusionadas, las organizaciones pueden importar los recursos de varias API de AWS AppSync de orígenes independientes en un único punto de conexión de la API fusionada de AWS AppSync. Para ello, AWS AppSync le permite crear una lista de las API de origen de AWS AppSync y, a continuación, fusionar todos los metadatos asociados con las API de origen, incluidos el esquema, los tipos, las fuentes de datos, los solucionadores y las funciones, en una nueva API fusionada de AWS AppSync.

Durante las fusiones, pueden producirse conflictos de fusión debido a incoherencias en el contenido de los datos de la API de origen, como conflictos en la nomenclatura de los tipos cuando se combinan varios esquemas. En los casos de uso sencillos sin definiciones en el conflicto de las API de origen, no es necesario modificar los esquemas de las API de origen. La API fusionada resultante simplemente importa todos los tipos, solucionadores, orígenes de datos y funciones de las API de origen de AWS AppSync originales. En los casos de uso complejos en los que surjan conflictos, los usuarios o los 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 que se configuren en AWS AppSync posteriormente propagarán los cambios en las API de origen a la API fusionada asociada.

API fusionadas y federación

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 Las API fusionadas adoptan un enfoque de tiempo de compilación para la composición del esquema, en el que las API de origen se combinan en una API fusionada independiente. Otra opción consiste en colocar un enrutador en tiempo de ejecución en varias API de origen o gráficos secundarios. En este enfoque, el enrutador 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 servidores o gráficos secundarios subyacentes. La siguiente tabla compara el enfoque de tiempo de compilación de la API fusionada de AWS AppSync con los enfoques de tiempo de ejecución basados en enrutador para la composición del esquema de GraphQL:

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

* Las API fusionadas de AWS AppSync solo se pueden asociar a las API de origen de AWS AppSync. Si necesita asistencia para la composición de esquemas en gráficos secundarios tanto de AWS AppSync como ajenos a AWS AppSync, puede conectar una o más API fusionadas o de GraphQL de AWS AppSync a una solución basada en enrutadores. Por ejemplo, consulte el blog de referencia para agregar API de AWS AppSync como gráfico secundario mediante una arquitectura basada en enrutadores con Apollo Federation v2: Apollo GraphQL Federation with AWS AppSync.

Resolución de conflictos de la API fusionada

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

Directivas de esquema de la API fusionada

AWS AppSync ha introducido varias directivas de GraphQL que se pueden utilizar para reducir o resolver conflictos entre las API de origen:

  • @canonical: esta directiva establece la prioridad de los tipos o campos con nombres y datos similares. Si dos o más API de origen tienen el mismo tipo o campo de GraphQL, una de las API puede anotar su tipo o campo como canónico, y este se priorizará durante la fusión. Los tipos o campos en conflicto que no estén anotados en esta directiva en otras API de origen se ignoran al fusionarse.

  • @hidden: esta directiva encapsula ciertos tipos o campos para eliminarlos del proceso de fusión. Los equipos tal vez deseen eliminar u ocultar tipos u operaciones específicos en la API de origen para que solo los clientes internos puedan acceder a datos de tipos específicos. Con esta directiva adjunta, los tipos o campos no se fusionan en la API fusionada.

  • @renamed: esta directiva cambia los nombres de los tipos o campos para reducir los conflictos de nomenclatura. Hay situaciones en las que diferentes API tienen el mismo tipo o nombre de campo. Sin embargo, todas deben estar disponibles en el esquema fusionado. Una forma sencilla de incluirlos todos en la API fusionada consiste en cambiar el nombre del campo por uno similar, pero no idéntico.

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

En este ejemplo, supongamos que queremos fusionar dos API de origen. 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:

  • Se priorizó el tipo User de Source1.graphql con respecto al User de Source2.graphql debido a la anotación @canonical.

  • El tipo Message de Source1.graphql se incluyó en la fusión. Sin embargo, había un conflicto de nombres en el Message de Source2.graphql. Al tener la anotación @renamed, también se incluyó en la fusión, pero con el nombre alternativo ChatMessage.

  • Se incluyó el tipo Post de Source1.graphql, pero no el tipo Post de Source2.graphql. Normalmente, habría un conflicto con este tipo, pero el tipo Post de Source2.graphql tenía una anotación @hidden, por lo que sus datos estaban ocultos y no se incluyeron en la fusión. Por tanto, no hubo conflicto.

  • El tipo Query se actualizó para incluir el contenido de ambos archivos. Sin embargo, la directiva hizo que se cambiara el nombre de una consulta de GetMessage a GetChatMessage. Así se resolvió el conflicto de nomenclatura entre las dos consultas con el mismo nombre.

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:

  • Con el tipo Mutation no se produjo ningún conflicto y este se fusionó.

  • Los campos del tipo Post se combinaron con una operación de unión. Observe que la unión entre los dos generó un único id, un title y una única reviews.

  • Con el tipo Review no se produjo ningún conflicto y este se fusionó.

  • Con el tipo Query no se produjo ningún conflicto y este se fusionó.

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 la consulta anterior se ejecuta mediante un cliente para el punto de conexión de la API fusionada, el servicio AWS AppSync ejecuta primero el solucionador de unidades para Query.getPost desde Source1, que llama a 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 fusionar estos dos esquemas, se producirá un error de fusión, ya que las API fusionadas de AWS AppSync no permiten que haya varios solucionadores de origen asociados 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 conflicto requiere que se reescriban los esquemas de las API de origen 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

Hay dos partes responsables de configurar los esquemas para crear una API fusionada:

  • Propietarios de las API fusionadas: los propietarios de las API fusionadas deben configurar la lógica de autorización de la API fusionada y los ajustes avanzados, como el registro, el seguimiento, el almacenamiento en caché y la compatibilidad con el WAF.

  • Propietarios de las API de origen asociadas: los propietarios de las API asociadas deben configurar los esquemas, los solucionadores y los orígenes de datos que componen la API fusionada.

Como el esquema de la API fusionada se crea a partir de los esquemas de sus API de origen asociadas, este es de solo lectura. Esto significa que los cambios en el esquema deben iniciarse en las API de origen. En la consola AWS AppSync, puede cambiar entre su esquema fusionado y los esquemas individuales de las API de origen incluidas en su API fusionada. Para ello, use la lista desplegable situada encima de la ventana Esquema.

Configuración de modos de autorización

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

Los modos de autorización siguientes están disponibles para su uso con las API fusionadas:

  • Clave de la API: la estrategia de autorización más sencilla. Todas las solicitudes deben incluir una clave de la API en el encabezado de la solicitud x-api-key. Las claves de la API vencidas se conservan durante 60 días después de la fecha de vencimiento.

  • AWS Identity and Access Management (IAM): la estrategia de autorización de AWS IAM autoriza todas las solicitudes firmadas mediante sigv4.

  • Grupos de usuarios de Amazon Cognito: autorice a sus usuarios a través de los grupos de usuarios de Amazon Cognito para lograr un control más detallado.

  • Autorizadores de AWS Lambda: función sin servidor que permite autenticar y autorizar el acceso a la API de AWS AppSync mediante una lógica personalizada.

  • OpenID Connect: este tipo de autorización aplica tókenes de OpenID Connect (OIDC) proporcionados por un servicio compatible con OIDC. Su aplicación puede aprovechar los usuarios y los privilegios definidos por su proveedor OIDC para controlar el acceso.

Los modos de autorización de una API fusionada los configura el propietario de la API fusionada. Al llevar a cabo una operación de fusión, la API fusionada debe incluir el modo de autorización principal configurado en una API de origen, 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 las API de origen, el proceso de fusión puede fusionar automáticamente estas directivas en el punto de conexión unificado. Si el modo de autorización principal de la API de origen no coincide con el modo de autorización principal de la API fusionada, este agregará automáticamente estas directivas de autorización para garantizar que el modo de autorización de los tipos de la API de origen sea coherente.

Configuración de roles de ejecución

Al crear una API fusionada, es necesario definir un rol de servicio. Un rol de servicio de AWS es un rol de AWS Identity and Access Management (IAM) que utilizan los servicios de AWS para realizar tareas en su nombre.

En este contexto, su API fusionada debe ejecutar solucionadores que accedan a los datos de orígenes de datos configurados en sus API de origen. El rol de servicio necesario para ello es mergedApiExecutionRole, y este debe tener acceso explícito para ejecutar solicitudes en las API de origen incluidas en la API fusionada mediante el permiso appsync:SourceGraphQL de IAM. Durante la ejecución de una solicitud de GraphQL, el servicio AWS AppSync asumirá este rol de servicio y lo autorizará a realizar la acción appsync:SourceGraphQL.

AWS AppSync admite la opción de permitir o denegar este permiso en campos específicos de nivel superior de la solicitud; por ejemplo, cómo actúa el modo de autorización de IAM para las API de IAM. Para los campos que no son de nivel superior, AWS AppSync le solicitará que defina el permiso en el propio ARN de la API de origen. Para restringir el acceso a campos específicos que no son de nivel superior en la API fusionada, le recomendamos implementar una lógica personalizada en su Lambda u ocultar los campos de la API de origen de la API fusionada mediante la directiva @hidden. Si quiere permitir que el rol realice todas las operaciones de datos dentro de una API de origen, puede agregar 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 los solucionadores secundarios que autorizan en el propio recurso de la API 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 puede usar el asistente de creación de API de la consola de AWS AppSync para generar un rol de servicio que permita que la API fusionada acceda a los recursos configurados en las API de origen ubicadas en la misma cuenta que la API fusionada. En el caso de que las API de origen no estén en la misma cuenta que la API fusionada, primero debe compartir los recursos mediante AWS Resource Access Manager (AWS RAM).

Configuración de API fusionadas entre cuentas mediante AWS RAM

Al crear una API fusionada, si lo desea, puede asociar las API de origen 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 cuentas de AWS, dentro de su organización o en unidades organizativas (OU) y con roles y usuarios de IAM.

AWS AppSync se integra con AWS RAM para permitir la configuración y el acceso a las API de origen en varias cuentas desde una única API fusionada. 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 agregar API de AWS AppSync 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 API de AWS AppSync en RAM:

  1. AWSRAMPermissionAppSyncSourceApiOperationAccess: el conjunto de permisos predeterminado que se agrega al compartir una API de AWS AppSync en AWS RAM si no se especifica ningún otro permiso. Este conjunto de permisos se utiliza para compartir una API de origen de AWS AppSync con el propietario de una API fusionada. Este conjunto de permisos incluye el permiso appsync:AssociateMergedGraphqlApi en la API de origen, así como el permiso appsync:SourceGraphQL necesario para acceder a los recursos de la API de origen en tiempo de ejecución.

  2. AWSRAMPermissionAppSyncMergedApiOperationAccess: este conjunto de permisos debe configurarse al compartir una API fusionada con el propietario de una API de origen. Este conjunto de permisos permite a la API de origen configurar la API fusionada, incluida la posibilidad de asociar cualquier API de origen que sea propiedad de la entidad principal de destino con la API fusionada, así como de leer y actualizar las asociaciones con la API de origen de la API fusionada.

  3. AWSRAMPermissionAppSyncAllowSourceGraphQLAccess: este conjunto de permisos permite utilizar el permiso appsync:SourceGraphQL con una API de AWS AppSync. La finalidad prevista de este permiso es la de compartir una API de origen con el propietario de una API fusionada. A diferencia del conjunto de permisos predeterminado para el acceso a las operaciones de la API de origen, este conjunto de permisos solo incluye el permiso de tiempo de ejecución appsync:SourceGraphQL. Si un usuario opta por compartir el acceso a la operación de la API fusionada con el propietario de la API de origen, también tendrá que compartir este permiso de la API de origen con el propietario de la API fusionada para tener acceso en tiempo de ejecución a través del punto de conexión de la API fusionada.

AWS AppSync también admite permisos administrados por el cliente. Si uno de los permisos administrados por AWS facilitados no funciona, puede crear su propio permiso administrado por el cliente. Los permisos administrados por el cliente son permisos administrados que usted crea y mantiene especificando exactamente qué acciones se pueden llevar a cabo y en qué condiciones con los recursos que se comparten mediante AWS RAM. AWS AppSync le permite elegir entre las siguientes acciones al crear su propio permiso:

  1. appsync:AssociateSourceGraphqlApi

  2. appsync:AssociateMergedGraphqlApi

  3. appsync:GetSourceApiAssociation

  4. appsync:UpdateSourceApiAssociation

  5. appsync:StartSchemaMerge

  6. appsync:ListTypesByAssociation

  7. appsync:SourceGraphQL

Cuando haya compartido adecuadamente una API de origen o una API fusionada AWS RAM y, en caso necesario, se haya aceptado la invitación para compartir recursos, podrá verse en la consola de AWS AppSync cuando cree o actualice las asociaciones de la API de origen en su API fusionada. También puede enumerar todas las API de AWS AppSync que se han compartido con su cuenta mediante AWS RAM, independientemente del permiso definido, llamando a la operación ListGraphqlApis proporcionada por AWS AppSync y utilizando el filtro del propietario OTHER_ACCOUNTS.

nota

Para compartir mediante AWS RAM, la persona que llama en AWS RAM debe tener permiso para realizar la acción appsync:PutResourcePolicy en cualquier API que se vaya a compartir.

Fusión

Administración de fusiones

Las API fusionadas están diseñadas para respaldar la colaboración en equipo en un punto de conexión de AWS AppSync unificado. Los equipos pueden desarrollar por su cuenta sus propias API de origen de GraphQL aisladas en el backend mientras el servicio AWS AppSync gestiona la integración de los recursos en el punto de conexión único de la API fusionada para reducir la fricción en la colaboración y reducir los plazos de desarrollo.

Fusiones automáticas

Las API de origen asociadas a su API fusionada de AWS AppSync se pueden configurar para que se fusionen automáticamente (fusión automática) en la API fusionada después de hacer cambios en la API de origen. Esto garantiza que los cambios en la API de origen siempre se propaguen al punto de conexión de la API fusionada en segundo plano. Cualquier cambio en el esquema de la API de origen se actualizará en la API fusionada siempre y cuando no genere un conflicto de fusión con una definición existente en la API fusionada. Si la actualización de la API de origen actualiza un solucionador, un origen 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 (resolución automática), se rechaza la actualización del esquema de la API fusionada debido a un conflicto no admitido durante la operación de fusión. El mensaje de error está disponible en la consola para cada asociación de la API de origen cuyo estado sea MERGE_FAILED. También puede inspeccionar el mensaje de error llamando a la operación GetSourceApiAssociation de una asociación de API de origen determinada mediante el SDK de AWS o la CLI de AWS 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 predeterminada de una API de origen es una fusión manual. Para fusionar cualquier cambio que se haya producido en las API de origen desde la última actualización de la API fusionada, el propietario de la API de origen puede invocar una fusión manual desde la consola de AWS AppSync o mediante la operación StartSchemaMerge disponible en el SDK de AWS y la CLI de AWS.

Asistencia adicional para las API fusionadas

Configuración de suscripciones

A diferencia de los enfoques basados en enrutadores para la composición de esquemas de GraphQL, las API fusionadas de AWS AppSync ofrecen asistencia integrada para las suscripciones de GraphQL. Todas las operaciones de suscripción definidas en sus API de origen asociadas se fusionarán automáticamente y funcionarán en la API combinada sin modificaciones. Para obtener más información sobre la compatibilidad de AWS AppSync con suscripciones a través de una conexión WebSockets sin servidor, consulte Datos en tiempo real.

Configuración de la observabilidad

Las API fusionadas de AWS AppSync proporcionan registro, supervisión y métricas integrados a través de Amazon CloudWatch. AWS AppSync también proporciona asistencia integrada para el rastreo mediante AWS X-Ray.

Configuración de dominios personalizados

Las API fusionadas de AWS AppSync proporcionan asistencia integrada para el uso de dominios personalizados con los puntos de conexión de GraphQL y en tiempo real de sus API fusionadas.

Configuración del almacenamiento en caché

Las API fusionadas de AWS AppSync ofrecen asistencia integrada para almacenar en caché, de forma opcional, las respuestas a nivel de solicitud o a nivel de solucionador, así como para la compresión de respuestas. Para obtener más información, consulte Almacenamiento en caché y compresión.

Configuración de API privadas

Las API fusionadas de AWS AppSync proporcionan asistencia integrada para las API privadas que limitan el acceso de los puntos de conexión de GraphQL y en tiempo real de sus API fusionadas al tráfico procedente de los puntos de conexión de la VPC que puede configurar.

Configuración de reglas de firewall

Las API fusionadas de AWS AppSync proporcionan asistencia integrada para AWS WAF, lo que le permite proteger sus API mediante la definición de reglas de firewall de aplicaciones web.

Configuración de registros de auditoría

Las API fusionadas de AWS AppSync proporcionan asistencia integrada para AWS CloudTrail, lo que le permite configurar y administrar los registros de auditoría.

Limitaciones de las API fusionadas

Tenga en cuenta las siguientes reglas cuando desarrolle API fusionadas:

  1. Una API fusionada no puede ser una API de origen para otra API fusionada.

  2. Una API de origen no se puede asociar a más de una API fusionada.

  3. El límite de tamaño predeterminado para un documento de esquema de API fusionada es de 10 MB.

  4. De manera predeterminada, el número de API de origen que se pueden asociar a una API fusionada es 10. No obstante, es posible solicitar un aumento de límite en caso de que sean necesarias más de 10 API de origen en su API fusionada.

Creación de API fusionadas

Para crear una API fusionada en la consola

  1. Inicie sesión en AWS Management Console y abra la consola de AWS AppSync.

    1. En el Panel, elija Crear API.

  2. Seleccione API fusionada y, a continuación, Siguiente.

  3. En la página Especificar los detalles de la API, introduzca la información siguiente:

    1. En Detalles de API, escriba la información siguiente:

      1. Especifique el Nombre de API de su API fusionada. Este campo es una forma de etiquetar su API de GraphQL para distinguirla fácilmente de otras API de GraphQL.

      2. Especifique los Datos de contacto. Este campo es opcional y adjunta un nombre o grupo a la API de GraphQL. No está vinculado a otros recursos ni es generado por ellos, y funciona de forma muy parecida al campo de nombre de la API.

    2. En Rol de servicio, debe asignar una función de ejecución de IAM a la API fusionada para que AWS AppSync pueda importar y utilizar sus recursos de forma segura en tiempo de ejecución. Puede optar por Crear y utilizar un nuevo rol de servicio, lo que le permitirá especificar las políticas y los recursos que utilizará AWS AppSync. También puede importar un rol de IAM existente seleccionando Usar un rol de servicio existente y, a continuación, seleccionando el rol en la lista desplegable.

    3. En Configuración de API privada, puede optar por habilitar las características de API privadas. Tenga en cuenta que esta opción no se puede cambiar después de crear la API fusionada. Para obtener más información acerca del uso de API privadas, consulte Uso de API privadas de AWS AppSync.

      Cuando haya terminado, elija Siguiente.

  4. A continuación, debe agregar las API de GraphQL que se usarán como base para la API fusionada. En la página Seleccionar API de origen, introduzca la siguiente información:

    1. En la tabla API de su cuenta de AWS, elija Agregar API de origen. En la lista de API de GraphQL, cada entrada contiene los siguientes datos:

      1. Nombre: el campo de nombre de la API de la API de GraphQL.

      2. ID de la API: el valor de ID único de la API de GraphQL.

      3. Modo de autorización principal: el modo de autorización predeterminado para la API de GraphQL. Para obtener más información sobre los modos de autorización en AWS AppSync, consulte Autorización y autenticación.

      4. Modos de autorización adicionales: los modos de autorización secundarios que se configuraron en la API de GraphQL.

      5. Seleccione las API que usará en la API fusionada. Para ello, seleccione la casilla de verificación situada junto al campo Nombre de la API. A continuación, seleccione Agregar API de origen. Las API de GraphQL seleccionadas aparecerán en la tabla API de sus cuentas de AWS.

    2. En la tabla API de sus cuentas de AWS, seleccione Agregar API de origen. Las API de GraphQL de esta lista provienen de otras cuentas que comparten sus recursos con la suya a través de AWS Resource Access Manager (AWS RAM). El proceso para seleccionar las API de GraphQL en esta tabla es el mismo que el proceso de la sección anterior. Para obtener más información sobre cómo compartir recursosAWS RAM, consulte ¿Qué es AWS Resource Access Manager? .

      Cuando haya terminado, elija Siguiente.

    3. Agregue su modo de autenticación principal. Para obtener más información, consulte Autorización y autenticación. Seleccione Siguiente.

    4. Revise la información indicada y, a continuación, seleccione Crear API.