APIs mescladas e federação Resolução de conflitos de API mesclada Configurar esquemas Configurar modos de autorização Configurar perfis de execução Configurar APIs mescladas entre contas usando o AWS RAM Mesclar Suporte adicional para APIs mescladas Limitações de APIs mescladas Criar APIs mescladas

APIs mescladas

À medida que o uso do GraphQL se expande dentro de uma organização, podem surgir concessões entre a facilidade de uso da API e a velocidade de desenvolvimento da API. Por um lado, as organizações adotam o AWS AppSync e GraphQL para simplificar o desenvolvimento de aplicativos, oferecendo aos desenvolvedores uma API flexível 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 da API GraphQL podem querer a capacidade de criar, gerenciar e implantar atualizações de API independentes umas das outras para aumentar suas velocidades de desenvolvimento.

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

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

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

As mesclagens subsequentes configuradas no AWS AppSync propagarão as alterações feitas nas APIs de origem para a API mesclada associada.

APIs mescladas e federação

Há muitas soluções e padrões na comunidade do GraphQL para combinar esquemas do GraphQL e permitir a colaboração em equipe por meio de um gráfico compartilhado. AWS AppSync As APIs mescladas adotam uma abordagem de tempo de compilação para a composição do esquema, em que as APIs de origem são combinadas em uma API mesclada separada. Uma abordagem alternativa é colocar um roteador em camadas em tempo de execução em várias APIs ou subgráficos de origem. Nessa abordagem, o roteador recebe uma solicitação, faz referência a um esquema combinado que ele mantém como metadados, estrutura 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 compilação da API mesclada do AWS AppSync com abordagens de runtime baseadas em roteador para a composição do esquema do 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

* As APIs mescladas do AWS AppSync só podem ser associadas às APIs de origem do AWS AppSync. Se você precisar de suporte para composição de esquemas entre subgráficos AWS AppSync e não AWS AppSync, você pode conectar um ou mais GraphQL e/ou APIs mescladas do AWS AppSync em uma solução baseada em roteador. Por exemplo, consulte o blog de referência para adicionar APIs do AWS AppSync como um subgráfico usando uma arquitetura baseada em roteador com o Apollo Federation v2: Apollo GraphQL Federation com AWS AppSync.

Tópicos

Resolução de conflitos de API mesclada
Configurar esquemas
Configurar modos de autorização
Configurar perfis de execução
Configurar APIs mescladas entre contas usando o AWS RAM
Mesclar
Suporte adicional para APIs mescladas
Limitações de APIs mescladas
Criar APIs mescladas

Resolução de conflitos de API mesclada

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

Diretivas de esquema de API mescladas

O AWS AppSync introduziu várias diretivas do GraphQL que podem ser usadas para reduzir ou resolver conflitos nas APIs de origem:

@canonical: essa diretiva define a precedência de tipos/campos com nomes e dados semelhantes. Se duas ou mais APIs de origem tiverem o mesmo tipo ou campo do GraphQL, uma das APIs poderá anotar seu tipo ou campo como canônico, o que será priorizado durante a mesclagem. Os tipos/campos conflitantes que não são anotados com essa diretiva em outras APIs de origem são ignorados quando mesclados.
@hidden: essa diretiva encapsula certos tipos/campos para removê-los do processo de mesclagem. As equipes podem querer remover ou ocultar tipos ou operações específicos na API de origem para que somente clientes internos possam acessar dados digitados específicos. Com essa diretiva anexada, os tipos ou campos não são mesclados na API mesclada.
@renamed: essa diretiva altera os nomes dos tipos/campos para reduzir os conflitos de nomenclatura. Há situações em que diferentes APIs têm o mesmo tipo ou nome de campo. No entanto, todos eles precisam estar disponíveis no esquema mesclado. Uma maneira simples de incluir todos eles na API mesclada é renomear o campo para algo semelhante, mas diferente.

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

Neste exemplo, vamos supor que queremos mesclar duas APIs de origem. 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:

O tipo User de Source1.graphql foi priorizado em relação ao de Source2.graphql devido à User anotação @canonical.
O Message tipo do Source1.graphql foi incluído na mesclagem. No entanto, o Message do source2.graphql teve um conflito de nomenclatura. Devido à anotação @renamed, ele também foi incluído na mesclagem, mas com o nome alternativo ChatMessage.
O tipo Post de Source1.graphql foi incluído, mas o tipo Post de Source2.graphql não. Normalmente, haveria um conflito nesse tipo, mas como o tipo Post de Source2.graphql tinha uma anotação @hidden, seus dados foram ofuscados e não incluídos na mesclagem. Isso não resultou em conflitos.
O tipo Query foi atualizado para incluir o conteúdo dos dois arquivos. No entanto, uma consulta GetMessage foi renomeada para GetChatMessage devido à diretiva. Isso resolveu o conflito de nomenclatura entre as duas consultas com o mesmo nome.

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:

O tipo Mutation não enfrentou conflitos e foi mesclado.
Os campos do tipo Post foram combinados por meio da operação de união. Observe como a união entre os dois produziu um único id, um title e um único reviews.
O tipo Review não enfrentou conflitos e foi mesclado.
O tipo Query não enfrentou conflitos e foi mesclado.

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 endpoint da API mesclada, o serviço AWS AppSync primeiro executa o resolvedor de unidades para Query.getPost a partir de Source1, 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 as APIs mescladas AWS AppSync não permitem 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 esquemas da API de origem sejam reescritos e, potencialmente, que os clientes alterem suas consultas, a vantagem dessa abordagem é que a propriedade dos resolvedores mesclados permanece clara entre todas as equipes de origem.

Configurar esquemas

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

Proprietários da API mesclada - Os proprietários da API mesclada devem definir a lógica de autorização e as configurações avançadas da API mesclada, como registro em log, rastreamento, armazenamento em cache e suporte ao WAF.
Proprietários da API de origem associada - Os proprietários da API associada devem configurar os esquemas, os resolvedores e as fontes de dados que compõem a API mesclada.

Como o esquema da API mesclada é criado a partir dos esquemas das APIs de origem associadas, ele é somente para leitura. Isso significa que as alterações no esquema devem ser iniciadas em suas APIs de origem. No console do AWS AppSync, você pode alternar entre o esquema mesclado e os esquemas individuais das APIs de origem incluídas na API mesclada 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 sua API mesclada. Para saber mais sobre os modos de autorização no AWS AppSync, consulte Autorização e autenticação.

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

Chave de API: a estratégia de autorização mais simples. Todas as solicitações devem incluir uma chave de API no cabeçalho da solicitação x-api-key. As chaves de API expiradas são mantidas por 60 dias após a data de expiração.
AWS Identity and Access Management (IAM): a estratégia de autorização IAM da AWS autoriza todas as solicitações assinadas com sigv4.
Grupos de usuários do Amazon Cognito: autorize seus usuários por meio dos grupos de usuários do Amazon Cognito para obter um controle mais refinado.
Autorizadores Lambda da AWS: uma função com tecnologia sem servidor que permite autenticar e autorizar o acesso à sua API usando lógica personalizada do AWS AppSync.
OpenID Connect: esse tipo de autorização impõe tokens do OpenID Connect (OIDC) fornecidos por um serviço compatível com OIDC. O aplicativo pode aproveitar os usuários e os privilégios definidos pelo provedor de OIDC para controlar o acesso.

Os modos de autorização de uma API mesclada são configurados pelo proprietário da API mesclada. No momento de uma operação de mesclagem, a API mesclada deve incluir o modo de autorização principal configurado em uma API de origem 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 nas APIs de origem, o processo de mesclagem é capaz de mesclar automaticamente essas diretivas no endpoint unificado. Caso o modo de autorização principal da API de origem não corresponda ao modo de autorização principal da API mesclada, ele adicionará automaticamente essas diretivas de autenticação para garantir que o modo de autorização dos tipos na API de origem seja consistente.

Configurar perfis de execução

Ao criar uma API mesclada, você precisa definir um perfil de serviço. Um perfil de serviço da AWS é um perfil da AWS Identity and Access Management (IAM) usado pelos serviços da AWS para realizar tarefas em seu nome.

Nesse contexto, é necessário que sua API mesclada execute resolvedores que acessem dados das fontes de dados configuradas nas APIs de origem. O perfil de serviço necessário para isso é o mergedApiExecutionRole, e ele deve ter acesso explícito para executar solicitações nas APIs de origem incluídas na sua API mesclada por meio da permissão do IAM appsync:SourceGraphQL. Durante a execução de uma solicitação do GraphQL, o serviço AWS AppSync assumirá esse perfil de serviço e o autorizará a a realizar a ação appsync:SourceGraphQL.

O AWS AppSync permite aceitar ou negar essa permissão em campos específicos de nível superior dentro da solicitação, incluindo a forma como o modo de autorização do IAM funciona para as APIs do IAM. Para campos que não são de nível superior, o AWS AppSync exige que você defina a permissão no próprio ARN da API de origem. Para restringir o acesso a campos específicos que não sejam de nível superior na API mesclada, recomendamos implementar uma lógica personalizada em seu Lambda ou ocultar os campos da API de origem da API mesclada usando a diretiva @hidden. Se você quiser permitir que o perfil execute todas as operações de dados em uma API de origem, 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 atributo da API de origem:


{
    "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 criação de API do console do AWS AppSync para gerar um perfil de serviço para permitir que sua API mesclada acesse atributos configurados nas APIs de origem que estão na mesma conta da sua API mesclada. Caso suas APIs de origem não estejam na mesma conta da API mesclada, você deve primeiro compartilhar seus atributos da AWS usando o Resource Access Manager (AWS RAM).

Configurar APIs mescladas entre contas usando o AWS RAM

Ao criar uma API mesclada, você tem a opção de associar APIs de origem de outras contas que foram compartilhadas por meio do Resource Access Manager (AWS RAM) da AWS. O AWS RAM ajuda você a compartilhar atributos com segurança entre contas da AWS, dentro de sua organização ou unidades organizacionais (OUs) e com perfis e usuários do IAM.

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

AWSRAMPermissionAppSyncSourceApiOperationAccess: o conjunto de permissões padrão que é adicionado ao compartilhar uma API do AWS AppSync no AWS RAM se nenhuma outra permissão for especificada. Esse conjunto de permissões é usado para compartilhar uma API de origem do AWS AppSync com um proprietário da API mesclada. Esse conjunto de permissões inclui a permissão para appsync:AssociateMergedGraphqlApi a API de origem, bem como a permissão appsync:SourceGraphQL necessária para acessar os atributos da API de origem em runtime.
AWSRAMPermissionAppSyncMergedApiOperationAccess: esse conjunto de permissões deve ser configurado ao compartilhar uma API mesclada com o proprietário da API de origem. Esse conjunto de permissões dará à API de origem a capacidade de configurar a API mesclada, incluindo a capacidade de associar quaisquer APIs de origem pertencentes à entidade principal de destino à API mesclada e de ler e atualizar as associações de API de origem da API mesclada.
AWSRAMPermissionAppSyncAllowSourceGraphQLAccess: esse conjunto de permissões permite que a permissão appsync:SourceGraphQL seja usada com uma API do AWS AppSync. Ele deve ser usado para compartilhar uma API de origem com um proprietário da API mesclada. Ao contrário do conjunto de permissões padrão para acesso à operação da API de origem, esse conjunto de permissões inclui apenas a permissão de runtime appsync:SourceGraphQL. Se um usuário optar por compartilhar o acesso à operação da API mesclada com um proprietário da API de origem, ele também precisará compartilhar essa permissão da API de origem com o proprietário da API mesclada para ter acesso de runtime por meio do endpoint da API mesclada.

O AWS AppSync também oferece suporte a permissões gerenciadas pelo cliente. Quando uma das permissões gerenciadas da AWS 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 atributos compartilhados e do AWS RAM. O AWS AppSync permite que você escolha entre as seguintes ações ao criar sua própria permissão:

appsync:AssociateSourceGraphqlApi
appsync:AssociateMergedGraphqlApi
appsync:GetSourceApiAssociation
appsync:UpdateSourceApiAssociation
appsync:StartSchemaMerge
appsync:ListTypesByAssociation
appsync:SourceGraphQL

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

nota

O compartilhamento por meio do AWS RAM exige que o chamador do AWS RAM tenha permissão para realizar a ação appsync:PutResourcePolicy em qualquer API que esteja sendo compartilhada.

Mesclar

Gerenciar mesclagens

As APIs mescladas destinam-se a apoiar a colaboração em equipe em um endpoint unificado do AWS AppSync. As equipes podem desenvolver de forma independente suas próprias APIs de origem isolada do GraphQL no back-end, enquanto o serviço do AWS AppSync gerencia a integração dos recursos em um único endpoint da API mesclada, a fim de reduzir o atrito na colaboração e diminuir os prazos de desenvolvimento.

Mesclagens automáticas

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


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 API de origem é uma mesclagem manual. Para mesclar as alterações que ocorreram nas APIs de origem desde a última atualização da API mesclada, o proprietário da API de origem pode invocar uma mesclagem manual a partir do console do AWS AppSync ou por meio da operação StartSchemaMerge disponível no SDK da AWS e na CLI da AWS.

Suporte adicional para APIs mescladas

Configurar assinaturas

Diferentemente das abordagens baseadas em roteador para a composição do esquema do GraphQL, as APIs mescladas do AWS AppSync fornecem suporte integrado para assinaturas do GraphQL. Todas as operações de assinatura definidas em suas APIs de origem associadas serão mescladas e funcionarão automaticamente em sua API mesclada sem modificação. Para saber mais sobre como o AWS AppSync oferece suporte a assinaturas por meio de conexão WebSockets com tecnologia sem servidor , consulte Dados em tempo real.

Configurar a observabilidade

As APIs mescladas do AWS AppSync fornecem registros em log, monitoramento e métricas integrados por meio do Amazon CloudWatch. O AWS AppSync também fornece suporte integrado para rastreamento via AWS X-Ray.

Configurar domínios personalizados

As APIs mescladas do AWS AppSync fornecem suporte integrado para o uso de domínios personalizados com os endpoints do GraphQL e em tempo real da sua API mesclada.

Configurar o cache

As APIs mescladas do AWS AppSync fornecem suporte integrado para, opcionalmente, armazenar em cache as respostas no nível da solicitação e/ou no nível do resolvedor, bem como para a compactação das respostas. Para saber mais, consulte Armazenamento em cache e compactação.

Configurar APIs privadas

As APIs mescladas do AWS AppSync fornecem suporte integrado para APIs privadas que limitam o acesso aos endpoints do GraphQL e em tempo real da API mesclada ao tráfego proveniente de endpoints da VPC que você pode configurar.

Configurar regras de firewall

As APIs mescladas do AWS AppSync fornecem suporte integrado paraAWS WAF, o que permite que você proteja suas APIs definindo regras de firewall para aplicativos web.

Configurar logs de auditoria

As APIs mescladas do AWS AppSync fornecem suporte integrado para o AWS CloudTrail, o que permite configurar e gerenciar logs de auditoria.

Limitações de APIs mescladas

Antes de desenvolver APIs mescladas, observe as seguintes regras:

Uma API mesclada não pode ser uma API de origem para outra API mesclada.
Uma API de origem não pode ser associada a mais de uma API mesclada.
O limite de tamanho padrão para um documento do esquema da API mesclada é de 10 MB.
O número padrão de APIs de origem que podem ser associadas a uma API mesclada é 10. No entanto, será possível solicitar um aumento de limite se precisar de mais de dez APIs de origem na API mesclada.

Criar APIs mescladas

Para criar uma API mesclada no console

Faça login no AWS Management Console e abra o console do AWS AppSync.
1. No Painel, selecione Criar API.
Selecione API mesclada e, em seguida, Avançar.
Na página Especificar detalhes da API, insira as seguintes informações:
1. Em Detalhes da API, insira as seguintes informações:
  1. Especifique o nome da API da API mesclada. Esse campo é uma forma de identificar sua API do GraphQL para diferenciá-la convenientemente de outras APIs do GraphQL.
  2. Especifique os detalhes de contato. Esse campo é opcional e anexa um nome ou grupo à API do GraphQL. Ele não é vinculado ou gerado por outros atributos e funciona da mesma forma que o campo de nome da API.
2. Em Perfil de serviço, você deve anexar um perfil de execução do IAM à sua API mesclada para que o AWS AppSync possa importar e usar seus atributos com segurança em runtime. Você pode escolher Criar e usar um novo perfil de serviço, o que permitirá especificar as políticas e os atributos que o AWS AppSync usará. Você também pode importar um perfil do IAM existente escolhendo Usar um perfil de serviço existente e selecionando um perfil na lista suspensa.
3. Em Configuração da API privada, é possível ativar os atributos da API privada. Observe que essa opção não pode ser alterada após a criação da API mesclada. Para obter mais informações sobre como usar APIs privadas, consulte Usando APIs privadas do AWS AppSync.
  
  Quando terminar, selecione Avançar.
Em seguida, você deve adicionar as APIs do GraphQL que serão usadas como base para sua API mesclada. Na página Selecionar APIs de origem, insira as seguintes informações:
1. Na tabela APIs da sua conta da AWS, selecione Adicionar APIs de origem. Na lista de APIs do GraphQL, cada entrada conterá os seguintes dados:
  1. Nome: o campo nome da API da API do GraphQL.
  2. ID da API: o valor de ID exclusivo da API do GraphQL.
  3. Modo de autenticação primária: o modo de autorização padrão para a API do GraphQL. Para obter mais informações sobre os modos de autorização no AWS AppSync, consulte Autorização e autenticação.
  4. Modo de autenticação adicional: os modos de autorização secundários que foram configurados na API do GraphQL.
  5. Escolha as APIs que você usará na API mesclada marcando a caixa de seleção ao lado do campo Nome da API. Depois, selecione Adicionar APIs de origem. As APIs do GraphQL selecionadas aparecerão na tabela APIs da sua conta da AWS.
2. Na tabela APIs de outras contas da AWS, selecione Adicionar APIs de origem. As APIs do GraphQL nesta lista vêm de outras contas que estão compartilhando atributos com a sua por meio do AWS Resource Access Manager (AWS RAM). O processo para selecionar as APIs do GraphQL nesta tabela é o mesmo da seção anterior. Para obter mais informações sobre o compartilhamento de recursos por meio do AWS RAM, consulte O que é AWS Resource Access Manager? .
  
  Quando terminar, selecione Avançar.
3. Adicione seu modo de autenticação principal. Consulte Autorização e autenticação para obter mais informações. Selecione Avançar.
4. Revise suas entradas e selecione Criar API.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Criar um cliente WebSocket em tempo real

Introspecção do RDS