Criar uma conexão

Uma conexão associa uma fonte de dados a uma URL da API do Sheet Best. Escolha a fonte conforme os dados de que você precisa:

1. A partir de uma URL do Google Sheets (a planilha precisa ser compartilhada por link).
2. A partir de uma pasta do Google Drive: uma listagem somente para leitura com IDs, nomes e links dos arquivos.
3. Enviando um arquivo de planilha para o Sheet Best.

Uma quarta opção, Conectar com o Drive (beta), conecta uma única planilha privada sem torná-la pública. É um recurso separado da listagem de pastas.

As conexões do Google Sheets usam /sheets/<connection-id>, as pastas do Drive usam /drives/<connection-id> e os arquivos enviados usam /uploads/<connection-id>. Sempre copie a URL da conexão (Connection URL) no painel; seu ID é o da conexão do Sheet Best, não o do arquivo ou da pasta do Google.

Abra o painel do Sheet Best e clique em + CONNECTION para começar.

A partir de uma URL do Google Sheets

1. No Google Sheets, clique em Compartilhar e conceda Qualquer pessoa com o link → Leitor (ou Editor para gravações). Veja as imagens em Prepare sua planilha.

2. Copie a URL da planilha na barra de endereços do navegador.

3. No painel do Sheet Best, dê um nome à conexão, escolha Google Sheets como origem (Connection Origin), cole a URL e clique em CONNECT.

   

4. Abra os detalhes (DETAILS) da nova conexão e copie sua URL (Connection URL).

   

A partir de uma pasta do Google Drive

Use uma conexão de pasta como catálogo de arquivos em JSON. Por exemplo, use os nomes, IDs e links retornados para criar:

• Uma lista de downloads de documentos compartilhados.
• Uma galeria de imagens com arquivos de imagem acessíveis.
• Um diretório de recursos para um site ou aplicativo.

Os links dependem das configurações de compartilhamento e do tipo de cada arquivo. Verifique se funcionam para o download ou a exibição desejados; documentos nativos do Google podem precisar de outra URL de exportação ou visualização.

:::note As linhas de uma planilha precisam de uma conexão de planilha Uma conexão de pasta não lê células nem combina planilhas em uma única API. Para ler as linhas de uma planilha, crie uma conexão do Google Sheets para ela usando sua URL ou o seletor de planilhas privadas. Cada conexão de planilha conta separadamente para o limite de conexões do seu plano. :::

Seu plano precisa incluir conexões de pastas do Google Drive. O período de avaliação Starter/Free aceita apenas conexões do Google Sheets. Veja os planos e preços.

1. No Google Drive, clique com o botão direito na pasta e selecione Obter link.

   

2. Defina a permissão da pasta como Qualquer pessoa com o link → Leitor e copie o link. Os arquivos que você deseja listar também precisam estar acessíveis por meio do compartilhamento.

   

3. No painel, escolha Google Drive como origem (Connection Origin), cole o link da pasta e clique em CONNECT.

4. Abra os detalhes (DETAILS) e copie a URL da conexão (Connection URL). Teste com:

   curl https://api.sheetbest.com/drives/YOUR_CONNECTION_ID

   Uma pasta com arquivos retorna seus metadados, ordenados por nome:

   [
     {
       "id": "GOOGLE_FILE_ID",
       "name": "product-photo.png",
       "link": "https://drive.google.com/uc?export=view&id=GOOGLE_FILE_ID"
     }
   ]

   O id retornado é um ID de arquivo do Google. Não é um ID de conexão do Sheet Best nem um endpoint para as linhas dessa planilha. Uma pasta vazia e acessível retorna [].

Uma conexão de pasta ocupa um espaço de conexão. Novos arquivos podem aparecer na listagem após a atualização do cache, sem criar novas conexões do Sheet Best. Isso não fornece APIs de linhas de planilha para esses arquivos. A saída padrão é um array de registros; _format=index apenas altera a estrutura dos mesmos metadados. Suas chaves de índice não são identificadores de arquivo estáveis; use id para identificar um arquivo.

:::caution Limites da listagem O conector lista os itens diretamente contidos na pasta sem percorrer subpastas. Atualmente, ele busca apenas a primeira página de resultados do Google Drive, portanto listagens maiores podem estar incompletas. Ele não fornece um token de continuação nem uma forma de buscar as páginas seguintes. :::

O status Valid de uma URL não confirma que o Google consegue ler a pasta. O rótulo Read Only do formulário não mede suas permissões de compartilhamento no Google. As conexões de pasta são somente para leitura, mesmo com compartilhamento como Editor.

Enviando um arquivo

Use esta opção para planilhas avulsas que não estejam no Google Drive.

1. No painel, escolha o envio de arquivos (File Upload) como origem (Connection Origin).

2. Selecione o arquivo no seu computador no campo File e clique em CONNECT.

   

3. Abra os detalhes (DETAILS) e copie a URL da conexão (Connection URL).

   

Teste sua conexão

Os exemplos a seguir são para uma conexão do Google Sheets. Para um arquivo enviado, use a URL copiada /uploads/<connection-id>. Para uma pasta, use o exemplo acima com /drives/<connection-id>.

cURL

curl https://api.sheetbest.com/sheets/YOUR_SHEET_ID

JavaScript

fetch("https://api.sheetbest.com/sheets/YOUR_SHEET_ID")
  .then((r) => r.json())
  .then(console.log);

Python

import requests

print(requests.get('https://api.sheetbest.com/sheets/YOUR_SHEET_ID').json())

Nas conexões de planilhas, você deve receber um array de objetos, um por linha da planilha. As conexões de pasta retornam um registro de metadados para cada arquivo listado.

Permissões e gravações

A compatibilidade com gravações depende do tipo de conexão, das permissões da fonte, dos métodos permitidos e do plano:

• URL do Google Sheets: precisa de compartilhamento como Editor.
• Pasta do Google Drive: somente para leitura. POST, PUT, PATCH e DELETE retornam 405 Method Not Allowed, mesmo que a pasta esteja compartilhada como Editor.
• Envio de arquivos: permite gravações nos dados enviados.
• Conectar com o Drive: permite gravações na planilha quando a conta do Google conectada tem permissão de edição.

Nas conexões de planilhas, uma falha de gravação porque a planilha de origem não é editável pode retornar o código write_error. Isso é diferente da resposta de método não permitido de uma pasta. Veja Códigos de erro.

Proteja a API com uma chave

Por padrão, qualquer pessoa que tenha a URL da conexão pode acessá-la. Em um plano que aceite chaves de API, exija um cabeçalho X-Api-Key editando a conexão (Edit), abrindo as configurações avançadas (Advanced Settings) e habilitando a chave de API.

Veja os detalhes em Autenticação.

A seguir

• Ler dados com GET
• Trabalhar com abas
• Filtrar e consultar