Como Definir Limites de Capacidade da Integração com a API do Notion Workspace

Ao conectar aplicativos de terceiros ao seu workspace do Notion, cada integração pode acessar bancos de dados, páginas e blocos. Sem limites, uma única integração pode consumir toda a cota de taxa da API ou expor mais dados do que o pretendido. Este artigo explica como definir limites de capacidade da integração com a API no seu workspace do Notion para controlar o que cada integração pode fazer e quanto ela pode solicitar.

O Notion fornece configurações em nível de workspace para gerenciar integrações conectadas. Você pode restringir uma integração a páginas específicas, desabilitar o acesso de gravação ou revogar seu token completamente. As etapas abaixo cobrem como configurar esses limites para integrações existentes e novas.

Você aprenderá como encontrar o gerenciador de integrações, modificar permissões e aplicar o escopo correto para cada caso de uso. O artigo também aborda erros comuns que quebram uma integração e como evitá-los.

Entendendo as Capacidades da Integração com a API do Notion

Cada integração do Notion, seja pública ou interna, recebe um conjunto de capacidades quando seu token é criado. Essas capacidades definem o que a integração pode fazer através da API do Notion. Os principais grupos de capacidade são:

• Ler conteúdo — permite que a integração leia páginas, bancos de dados, blocos e suas propriedades.
• Inserir conteúdo — permite que a integração crie novas páginas, bancos de dados e blocos.
• Atualizar conteúdo — permite que a integração modifique páginas, bancos de dados, blocos e propriedades existentes.
• Excluir conteúdo — permite que a integração remova páginas, bancos de dados e blocos.

Cada integração também tem um limite de taxa. O Notion impõe um máximo de três solicitações por segundo por integração. Se uma integração exceder essa taxa, o Notion retorna um erro 429 Too Many Requests. Os limites de capacidade não afetam diretamente os limites de taxa, mas restringir capacidades pode reduzir o número de solicitações que uma integração faz, ajudando indiretamente a permanecer abaixo do teto de taxa.

Proprietários e administradores do workspace também podem controlar quais páginas uma integração pode acessar. Por padrão, uma integração tem acesso a todas as páginas do workspace. Você pode remover esse acesso e concedê-lo apenas a páginas ou bancos de dados específicos. Esta é a maneira mais eficaz de limitar quais dados uma integração pode ler ou modificar.

Etapas para Configurar Limites de Capacidade da Integração com a API

Siga estas etapas para configurar limites de capacidade para uma integração existente em seu workspace do Notion. O processo se aplica tanto a integrações internas que você criou quanto a integrações públicas que você conectou do diretório de integrações do Notion.

1. Abra o Gerenciador de Integrações
   Vá para Configurações e Membros na barra lateral esquerda. Na seção Workspace, clique em Meus aplicativos conectados. Você verá uma lista de todas as integrações conectadas ao seu workspace.
2. Selecione a Integração a Modificar
   Encontre a integração que deseja limitar. Clique no nome dela para abrir o painel de detalhes da integração. O painel mostra o nome da integração, ícone e as permissões que ela possui atualmente.
3. Ajuste as Alternâncias de Capacidade
   Na seção Capacidades, você verá alternâncias para Ler conteúdo, Inserir conteúdo, Atualizar conteúdo e Excluir conteúdo. Desative qualquer capacidade que deseja revogar. Por exemplo, se a integração deve apenas ler dados, desative Inserir, Atualizar e Excluir. Clique em Salvar alterações.
4. Restrinja o Acesso a Páginas
   Abaixo das capacidades, você verá Acesso a páginas. Por padrão, está definido como Todas as páginas. Clique em Alterar e selecione Páginas específicas. Uma caixa de pesquisa aparece. Digite o nome da página ou banco de dados que a integração deve acessar. Você pode adicionar várias páginas. Clique em Confirmar.
5. Revogue o Token da Integração se Necessário
   Se você quiser desabilitar completamente a integração, clique em Remover integração na parte inferior do painel. Isso revoga o token. A integração receberá um erro 401 Unauthorized na próxima chamada de API. Para reativá-la mais tarde, você deve gerar um novo token e reconectar.

Criando uma Nova Integração Interna com Capacidades Limitadas

Se você está construindo uma nova integração do zero, pode definir suas capacidades no momento da criação. Isso impede que a integração tenha acesso total.

1. Vá para a Página de Integrações Internas
   Navegue até https://www.notion.so/my-integrations. Clique em Nova integração.
2. Nomeie a Integração e Selecione o Workspace
   Dê à integração um nome descritivo. Escolha o workspace onde ela operará. Clique em Enviar.
3. Configure as Capacidades
   Na página de detalhes da integração, role até Capacidades. Você verá as mesmas quatro alternâncias. Desative qualquer capacidade que a integração não precise. Para uma integração somente leitura, desative Inserir, Atualizar e Excluir.
4. Gere o Token
   Clique em Mostrar token e copie o segredo. Este token agora carrega apenas as capacidades que você ativou. Cole-o no código da sua aplicação.
5. Compartilhe a Integração com Páginas Específicas
   Em seu workspace do Notion, vá para a página ou banco de dados que você deseja que a integração acesse. Clique no menu de três pontos no canto superior direito. Selecione Conexões e encontre sua nova integração. Clique em Conectar. A integração agora pode interagir apenas com essa página e seus filhos.

Erros Comuns ao Definir Limites de Integração com a API

Integração Para de Funcionar Após Alterar Capacidades

Se você desabilitar uma capacidade da qual a integração depende, ela falhará na próxima chamada de API que exigir essa capacidade. Por exemplo, se você desabilitar Inserir conteúdo, a integração não poderá criar novos itens de banco de dados. A API retorna um erro 403 Forbidden. Para corrigir, reative a capacidade ausente no painel de detalhes da integração.

Integração Não Consegue Acessar uma Página Após Restringir o Acesso

Quando você altera o acesso a páginas de Todas as páginas para Páginas específicas, a integração perde o acesso a todas as páginas não adicionadas explicitamente. Se a integração precisar ler uma página pai para navegar até uma página filha, você deve adicionar tanto a página pai quanto a filha. Adicione as páginas uma a uma usando a caixa de pesquisa.

Erros de Limite de Taxa Após Restringir Capacidades

Restringir capacidades não altera o limite de taxa de três solicitações por segundo. Se sua integração ainda atingir o limite de taxa, você deve implementar lógica de repetição com backoff exponencial no código da sua aplicação. O Notion não fornece uma maneira de aumentar o limite de taxa para qualquer integração.

Comparação dos Limites de Capacidade da Integração com a API do Notion

Capacidade	Padrão (Acesso Total)	Somente Leitura	Limitado Personalizado
Ler conteúdo	Ativado	Ativado	Ativado ou desativado
Inserir conteúdo	Ativado	Desativado	Ativado ou desativado
Atualizar conteúdo	Ativado	Desativado	Ativado ou desativado
Excluir conteúdo	Ativado	Desativado	Ativado ou desativado
Acesso a páginas	Todas as páginas	Páginas específicas	Páginas específicas
Limite de taxa	3 req/s	3 req/s	3 req/s

Agora você pode controlar o que cada integração do Notion pode ler, escrever, atualizar ou excluir. Comece revisando suas integrações existentes em Configurações e Membros > Meus aplicativos conectados e aplicando o conjunto mais restrito de capacidades que ainda permita que a integração funcione. Para novas integrações, sempre gere o token com apenas as capacidades necessárias. A combinação de alternâncias de capacidade e acesso em nível de página é a maneira mais precisa de limitar uma integração sem quebrá-la.