As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Mesclando em APIs AWS AppSync

À medida que o uso do GraphQL se expande dentro de uma organização, podem surgir compensações e a velocidade de desenvolvimento. API ease-of-use API Por um lado, as organizações adotam AWS AppSync o GraphQL para simplificar o desenvolvimento de aplicativos, oferecendo aos desenvolvedores uma flexibilidade API que eles podem usar para acessar, manipular e combinar com segurança dados de um ou mais domínios de dados com uma única chamada de rede. Por outro lado, as equipes de uma organização responsáveis pelos diferentes domínios de dados combinados em um único endpoint do API GraphQL podem querer a capacidade de criar, gerenciar e API implantar atualizações independentes umas das outras para aumentar suas velocidades de desenvolvimento.

Para resolver essa tensão, o APIs recurso AWS AppSync Merged permite que equipes de diferentes domínios de dados criem e implantem de forma independente AWS AppSync APIs (por exemplo, esquemas, resolvedores, fontes de dados e funções do GraphQL), que podem então ser combinadas em uma única fusão. API Isso dá às organizações a capacidade de manter um domínio API cruzado simples de usar e uma forma de as diferentes equipes que contribuem para isso API fazerem API atualizações de forma rápida e independente.

Usando o MergedAPIs, as organizações podem importar os recursos de várias fontes independentes AWS AppSync APIs em um único endpoint AWS AppSync mescladoAPI. Para fazer isso, AWS AppSync permite criar uma lista de fontes de AWS AppSync origem eAPIs, em seguida, mesclar todos os metadados associados à fonte, APIs incluindo esquema, tipos, fontes de dados, resolvedores e funções, em uma nova mesclagem. AWS AppSync API

Durante as mesclagens, existe a possibilidade de ocorrer um conflito de mesclagem devido a inconsistências no conteúdo dos API dados de origem, como conflitos de nomenclatura de tipos ao combinar vários esquemas. Para casos de uso simples em que nenhuma definição na fonte está em APIs conflito, não há necessidade de modificar os API esquemas de origem. O Merged resultante API simplesmente importa todos os tipos, resolvedores, fontes de dados e funções da fonte original. AWS AppSync APIs Para casos de uso complexos em que surgem conflitos, os usuários/equipes terão que resolver os conflitos por vários meios. AWS AppSync fornece aos usuários várias ferramentas e exemplos que podem reduzir os conflitos de mesclagem.

As mesclagens subsequentes configuradas em AWS AppSync propagarão as alterações feitas na origem APIs para o mesclado associado. API

Fusão APIs e federação

Há muitas soluções e padrões na comunidade GraphQL para combinar esquemas do GraphQL e permitir a colaboração em equipe por meio de um gráfico compartilhado. AWS AppSync Merged APIs adote uma abordagem de tempo de construção para a composição do esquema, em que APIs as fontes são combinadas em uma combinação separada, mesclada. API Uma abordagem alternativa é colocar um roteador em camadas em tempo de execução em várias fontes APIs ou subgráficos. Nessa abordagem, o roteador recebe uma solicitação, faz referência a um esquema combinado que ele mantém como metadados, constrói um plano de solicitação e, em seguida, distribui os elementos da solicitação em seus subgráficos/servidores subjacentes. A tabela a seguir compara a abordagem de tempo de AWS AppSync construção API mesclado com abordagens de tempo de execução baseadas em roteador para a composição do esquema GraphQL:

* O AWS AppSync mesclado só APIs pode ser associado à AWS AppSync fonteAPIs. Se precisar de suporte para composição de esquemas entre AWS AppSync e sem AWS AppSync subgráficos, você pode conectar um ou mais GraphQL e/ou APIs Merged em uma AWS AppSync solução baseada em roteador. Por exemplo, consulte o blog de referência para adicionar AWS AppSync APIs como subgráfico usando uma arquitetura baseada em roteador com o Apollo Federation v2: Apollo GraphQL Federation with. AWS AppSync

Resolução de API conflitos mesclada

No caso de um conflito de mesclagem, AWS AppSync fornece aos usuários várias ferramentas e exemplos para ajudar a solucionar o (s) problema (s).

Diretivas de API esquema mescladas

AWS AppSync introduziu várias diretivas do GraphQL que podem ser usadas para reduzir ou resolver conflitos na fonte: APIs

Para mostrar o esquema de utilitário fornecido pelas diretivas, considere o seguinte exemplo:

Neste exemplo, vamos supor que queremos mesclar duas fontesAPIs. Temos dois esquemas que criam e recuperam postagens (por exemplo, seção de comentários ou postagens em mídias sociais). Supondo que os tipos e campos sejam muito semelhantes, há uma grande chance de conflito durante uma operação de mesclagem. Os trechos abaixo mostram os tipos e campos de cada esquema.

O primeiro arquivo, chamado Source1.graphql, é um esquema do GraphQL que permite ao usuário criar Postsusando a mutação putPost. Cada Post contém um título e um ID. O ID é usado para referenciar as informações do autor ou do User (e-mail e endereço) e a Message, ou a carga útil (conteúdo). O tipo User é anotado com a 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
}

O segundo arquivo, chamado Source2.graphql, é um esquema do GraphQL que funciona muito semelhante ao Source1.graphql. No entanto, observe que os campos de cada tipo são diferentes. Ao mesclar esses dois esquemas, haverá conflitos de mesclagem devido a essas diferenças.

Além disso, observe como o Source2.graphql também contém várias diretivas para reduzir esses conflitos. O tipo Post é anotado com uma tag @hidden para se ofuscar durante a operação de mesclagem. O tipo Message é anotado com a tag @renamed para modificar o nome do tipo ChatMessage no caso de um conflito de nomenclatura com outro 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 a mesclagem ocorrer, o resultado produzirá o arquivo 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
}

Várias coisas ocorreram na mesclagem:

Também existe o caso de nenhuma diretiva ser adicionada a um tipo conflitante. Nesse caso, o tipo mesclado incluirá a união de todos os campos de todas as definições de origem desse tipo. Por exemplo, considere o exemplo a seguir:

Esse esquema, chamado Source1.graphql, permite criar e recuperar Posts. A configuração é semelhante à do exemplo anterior, mas com menos informações.

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

Esse esquema, chamado Source2.graphql, permite criar e recuperar Reviews (por exemplo, classificação de filmes ou resenhas de restaurantes). As Reviews estão associadas ao Post do mesmo valor de ID. Juntos, eles contêm o título, o ID da postagem e a mensagem da payload da postagem de avaliação completa.

Ao mesclar, haverá um conflito entre os dois tipos de Post. Como não há anotações para resolver esse problema, o comportamento padrão é realizar uma operação de união nos tipos conflitantes.

# 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 a mesclagem ocorrer, o resultado produzirá o arquivo 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
}

Várias coisas ocorreram na mesclagem:

Gerenciar resolvedores em tipos compartilhados

No exemplo acima, considere o caso em que o Source1.graphql configurou um resolvedor de unidades em Query.getPost, que usa uma fonte de dados do DynamoDB chamada PostDatasource. Esse resolvedor retornará o id e title de um tipo Post. Agora, considere que o Source2.graphql configurou um resolvedor de pipeline em Post.reviews, que executa duas funções. Function1tem uma fonte None de dados anexada para realizar verificações de autorização personalizadas. Function2tem uma fonte de dados do DynamoDB anexada para consultar a tabela. reviews

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

Quando a consulta acima é executada por um cliente no API endpoint mesclado, o AWS AppSync serviço primeiro executa o resolvedor de unidades para Query.getPost fromSource1, que chama PostDatasource e retorna os dados do DynamoDB. Em seguida, ele executa o resolvedor de pipeline Post.reviews, no qual Function1 executa a lógica de autorização personalizada e Function2 retorna as avaliações fornecidas ao id encontradas em $context.source. O serviço processa a solicitação como uma única execução do GraphQL, e essa solicitação simples exigirá apenas um único token de solicitação.

Gerenciar conflitos de resolvedor em tipos compartilhados

Considere o seguinte caso em que também implementamos um resolvedor em Query.getPost para fornecer vários campos ao mesmo tempo além do resolvedor de campo em Source2. Source1.graphql pode parecer da seguinte forma:

# This snippet represents a file called Source1.graphql

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

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

Source2.graphql pode parecer da seguinte forma:

# This snippet represents a file called Source2.graphql

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

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

A tentativa de mesclar esses dois esquemas gerará um erro de mesclagem porque o AWS AppSync Merged APIs não permite que vários resolvedores de origem sejam anexados ao mesmo campo. Para resolver esse conflito, você pode implementar um padrão de resolvedor de campo que exigiria que o Source2.graphql adicionasse um tipo separado que definirá os campos que ele possui do tipo Post. No exemplo a seguir, adicionamos um tipo chamado PostInfo, que contém os campos de conteúdo e autor que serão resolvidos pelo Source2.graphql. O Source1.graphql implementará o resolvedor anexado a Query.getPost, enquanto o Source2.graphql agora anexará um resolvedor a Post.postInfo para garantir que todos os dados possam ser recuperados com sucesso:

type Post  {
  id: ID!
  postInfo: PostInfo
}

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

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

Embora a resolução desse conflito exija que os API esquemas de origem sejam reescritos e, potencialmente, que os clientes alterem suas consultas, a vantagem dessa abordagem é que a propriedade dos resolvedores mesclados permanece clara em todas as equipes de origem.

Configurar esquemas

Duas partes são responsáveis por configurar os esquemas para criar um Merged: API

Como o esquema API do Merged é criado a partir dos esquemas da fonte associadaAPIs, ele é somente para leitura. Isso significa que as alterações no esquema devem ser iniciadas em sua fonteAPIs. No AWS AppSync console, você pode alternar entre o esquema mesclado e os esquemas individuais da fonte APIs incluídos no mesclado API usando a lista suspensa acima da janela Esquema.

Configurar modos de autorização

Vários modos de autorização estão disponíveis para proteger seu MergedAPI. Para saber mais sobre os modos de autorização em AWS AppSync, consulte Autorização e autenticação.

Os seguintes modos de autorização estão disponíveis para uso com o MergedAPIs:

Os modos de autorização de uma mesclada API são configurados pelo proprietário da mesclagemAPI. No momento de uma operação de mesclagem, a mesclada API deve incluir o modo de autorização principal configurado em uma fonte API como seu próprio modo de autorização principal ou como um modo de autorização secundário. Caso contrário, ela será incompatível e a operação de mesclagem falhará devido a um conflito. Ao usar diretivas de autenticação múltipla na origemAPIs, o processo de mesclagem é capaz de mesclar automaticamente essas diretivas no endpoint unificado. Caso o modo de autorização principal da fonte API não corresponda ao modo de autorização principal do MergedAPI, ele adicionará automaticamente essas diretivas de autenticação para garantir que o modo de autorização dos tipos na fonte API seja consistente.

Configurar perfis de execução

Ao criar um MergedAPI, você precisa definir uma função de serviço. Uma função AWS de serviço é uma função de AWS Identity and Access Management (IAM) usada pelos AWS serviços para realizar tarefas em seu nome.

Nesse contexto, é necessário que seu Merged API execute resolvedores que acessem dados das fontes de dados configuradas em sua fonte. APIs A função de serviço necessária para isso é amergedApiExecutionRole, e ela deve ter acesso explícito para executar solicitações na fonte APIs incluída em sua mesclagem API por meio da appsync:SourceGraphQL IAM permissão. Durante a execução de uma solicitação do GraphQL, o AWS AppSync serviço assumirá essa função de serviço e autorizará a função a realizar a ação. appsync:SourceGraphQL

AWS AppSync suporta permitir ou negar essa permissão em campos específicos de nível superior dentro da solicitação, por exemplo, para o funcionamento do modo de IAM autorização. IAM APIs Para non-top-level campos, AWS AppSync exige que você defina a permissão na API ARN própria fonte. Para restringir o acesso a non-top-level campos específicos no MergedAPI, recomendamos implementar uma lógica personalizada em seu Lambda ou ocultar os campos de API origem do API Merged usando a diretiva @hidden. Se você quiser permitir que a função execute todas as operações de dados em uma fonteAPI, adicione a política abaixo. Observe que a primeira entrada de recurso permite acesso a todos os campos de nível superior e a segunda entrada abrange resolvedores secundários que autorizam o próprio recurso de origem: 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 quiser limitar o acesso somente a um campo específico de nível superior, você pode usar uma 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"] 
    }] 
}

Você também pode usar o assistente de API criação de AWS AppSync console para gerar uma função de serviço para permitir que seu Merged API acesse recursos configurados na fonte APIs que estão na mesma conta da API mesclada. Caso sua fonte não APIs esteja na mesma conta da fusãoAPI, você deve primeiro compartilhar seus recursos usando o AWS Resource Access Manager (AWS RAM).

Configurando contas cruzadas mescladas usando APIs AWS RAM

Ao criar um MergedAPI, você pode, opcionalmente, associar a fonte APIs de outras contas que foram compartilhadas por meio do AWS Resource Access Manager ()AWS RAM. AWS RAM ajuda você a compartilhar seus recursos com segurança entre AWS contas, dentro de sua organização ou unidades organizacionais (OUs) e com IAM funções e usuários.

AWS AppSync se integra AWS RAM para oferecer suporte à configuração e ao acesso à fonte APIs em várias contas a partir de uma única fusão. API AWS RAM permite criar um compartilhamento de recursos ou um contêiner de recursos e os conjuntos de permissões que serão compartilhados para cada um deles. Você pode adicionar AWS AppSync APIs a um compartilhamento de recursos no AWS RAM. Em um compartilhamento de recursos, AWS AppSync fornece três conjuntos de permissões diferentes que podem ser associados a um AWS AppSync API inRAM:

AWS AppSync também oferece suporte a permissões gerenciadas pelo cliente. Quando uma das permissões AWS gerenciadas fornecidas não funciona, você pode criar sua própria permissão gerenciada pelo cliente. As permissões gerenciadas pelo cliente são permissões gerenciadas que você cria e mantém especificando com precisão quais ações podem ser executadas sob quais condições com o uso de recursos compartilhados. AWS RAM AWS AppSync permite que você escolha entre as seguintes ações ao criar sua própria permissão:

Depois de compartilhar adequadamente uma fonte API ou mesclada API AWS RAM e, se necessário, o convite de compartilhamento de recursos ter sido aceito, ele ficará visível no AWS AppSync console quando você criar ou atualizar as API associações de origem em seu API Merged. Você também pode listar tudo o AWS AppSync APIs que foi compartilhado usando AWS RAM sua conta, independentemente da permissão definida, chamando a ListGraphqlApis operação fornecida por AWS AppSync e usando o filtro do OTHER_ACCOUNTS proprietário.

Mesclar

Gerenciar mesclagens

APIsOs mesclados têm como objetivo apoiar a colaboração da equipe em um AWS AppSync endpoint unificado. As equipes podem desenvolver de forma independente sua própria fonte isolada de APIs GraphQL no back-end, enquanto AWS AppSync o serviço gerencia a integração dos recursos em um único endpoint API mesclado, a fim de reduzir o atrito na colaboração e diminuir os prazos de desenvolvimento.

Mesclagens automáticas

A fonte APIs associada à sua AWS AppSync mesclada API pode ser configurada para mesclar automaticamente (mesclagem automática) na mesclada API após qualquer alteração ser feita na fonte. API Isso garante que as alterações da origem API sejam sempre propagadas para o API endpoint mesclado em segundo plano. Qualquer alteração no API esquema de origem será atualizada no Merged, desde API que não introduza um conflito de mesclagem com uma definição existente no Merged. API Se a atualização na fonte API estiver atualizando um resolvedor, fonte de dados ou função, o recurso importado também será atualizado. Quando um novo conflito é introduzido e não pode ser resolvido automaticamente (resolvido automaticamente), a atualização do API esquema mesclado é rejeitada devido a um conflito sem suporte durante a operação de mesclagem. A mensagem de erro está disponível no console para cada API associação de origem que tenha um status deMERGE_FAILED. Você também pode inspecionar a mensagem de erro chamando a GetSourceApiAssociation operação de uma determinada API associação de origem usando o AWS SDK ou usando o AWS CLI seguinte:

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

Isso produzirá um resultado no seguinte 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."
    }
}

Mesclagens manuais

A configuração padrão para uma fonte API é uma mesclagem manual. Para mesclar quaisquer alterações que tenham ocorrido na fonte APIs desde a última atualização do MergedAPI, o API proprietário da fonte pode invocar uma mesclagem manual a partir do AWS AppSync console ou por meio da StartSchemaMerge operação disponível no e. AWS SDK AWS CLI

Suporte adicional para Merged APIs

Configurar assinaturas

Ao contrário das abordagens baseadas em roteador para a composição do esquema do GraphQL, o AWS AppSync Merged fornece suporte APIs integrado para assinaturas do GraphQL. Todas as operações de assinatura definidas em sua fonte associada APIs serão automaticamente mescladas e funcionarão em seu Merged API sem modificação. Para saber mais sobre como AWS AppSync oferece suporte a assinaturas por meio de WebSockets conexão sem servidor, consulte Dados em tempo real.

Configurar a observabilidade

AWS AppSync O Merged APIs fornece registro, monitoramento e métricas integrados via Amazon CloudWatch. AWS AppSync também fornece suporte integrado para rastreamento via AWS X-Ray.

Configurar domínios personalizados

AWS AppSync O Merged APIs fornece suporte integrado para o uso de domínios personalizados com os endpoints API GraphQL e Real-time do Merged.

Configurar o cache

AWS AppSync O Merged APIs fornece suporte integrado para armazenar, opcionalmente, em cache as respostas em nível de solicitação e/ou em nível de resolvedor, bem como compactação de respostas. Para saber mais, consulte Armazenamento em cache e compactação.

Configurando o privado APIs

AWS AppSync O Merged APIs fornece suporte integrado para Private, APIs que limita o acesso aos endpoints API GraphQL e Real-time do Merged ao tráfego VPC proveniente de endpoints que você pode configurar.

Configurar regras de firewall

AWS AppSync O Merged APIs fornece suporte integrado para AWS WAF, o que permite que você proteja você APIs definindo regras de firewall de aplicativos web.

Configurar logs de auditoria

AWS AppSync O Merged APIs fornece suporte integrado para AWS CloudTrail, o que permite configurar e gerenciar registros de auditoria.

Limitações mescladas API

Ao desenvolver o MergedAPIs, observe as seguintes regras:

Criando mesclado APIs

Para criar um mesclado API no console