Pular para o conteúdo principal

searchFileContent

Busque no texto de arquivos anexados a registros. Não é necessária autorização.

Descrição​

Busca no texto dos arquivos anexados aos seus registros (PDFs, documentos e similares). Resolve para um IFileSearchResponse com os arquivos correspondentes, cada um com o trecho em que a correspondência foi encontrada.

.searchFileContent(

, , , , , , ,

);

Esquema de parâmetros​

Schema

query(required): string
Consulta de busca, com pelo menos 3 caracteres — uma mais curta é rejeitada com 400.
exemplo: "transporte"

langCode: string
Idioma da consulta. Padrão: o langCode passado para defineOneEntry ("en_US" se nenhum for passado). Um código que a busca não suporta (por exemplo "xx_YY") é rejeitado com 400 "Unknown text search language".
exemplo: "en_US"

extensions: string[]
Filtrar pela extensão do arquivo, enviada separada por vírgula.
exemplo:

[
  "pdf",
  "docx"
]

ownerTables: string[]
Filtrar pela seção à qual pertence o registro anexado, enviada separada por vírgula.
exemplo:

[
  "products",
  "pages"
]

localeCodes: string[]
Filtrar pelo local do link, não do conteúdo do arquivo.
exemplo:

[
  "en_US"
]

onlyTruncated: boolean
Retornar apenas arquivos cujo texto extraído foi cortado no limite de tamanho.

offset: number
Número de registros a pular. Padrão: 0. offset + limit não pode ultrapassar 200; uma janela maior é rejeitada com 400.
exemplo: 0

limit: number
Número de arquivos a retornar. Padrão: 10, máximo 50; um valor maior é rejeitado com 400. offset + limit não pode ultrapassar 200.
exemplo: 10

O SDK sempre envia langCode, então, por padrão, a consulta é buscada no idioma do seu app e queryLanguage.source é "explicit". Uma consulta em outro alfabeto não é detectada automaticamente: uma consulta em cirílico com o padrão en_US ainda é buscada como inglês. Para que a API escolha o idioma a partir da consulta e das configurações do projeto, passe uma string vazia como langCode.

Antes de renderizar o resultado​

A unidade é um arquivo, não um trecho. Você recebe um snippet por arquivo, mesmo quando o documento corresponde em vinte páginas. snippet.pageFrom indica em qual página o trecho começa.

As correspondências são marcadas com caracteres de controle, não com HTML. Em snippet.text, cada correspondência fica entre U+0002 e U+0003. Se você inserir o texto na sua marcação sem alterações, o leitor não verá o destaque, então substitua-os pelos seus próprios. O texto vem do próprio arquivo, então escape-o primeiro e adicione as tags depois:

const escapeHtml = (text) =>
  text
    .replaceAll('&', '&')
    .replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;')
    .replaceAll('"', '&quot;');

const html = escapeHtml(item.snippet?.text ?? '')
  .replaceAll('\u0002', '<mark>')
  .replaceAll('\u0003', '</mark>');

O que a busca retorna​

A busca retorna apenas arquivos de registros visíveis, e apenas nas seções ativadas nas configurações do seu projeto. Seções pessoais são limitadas aos próprios registros de quem faz a chamada, e a seção de administradores nunca é retornada. Uma resposta 403 significa que a busca de arquivos não está incluída no seu plano.

Exemplos​

Exemplo mínimo​

const response = await FileUploading.searchFileContent('transportation');

Apenas PDFs anexados a produtos​

const response = await FileUploading.searchFileContent(
  'transportation',
  'en_US',
  ['pdf'],
  ['products'],
);

Segunda página​

const response = await FileUploading.searchFileContent(
  'transportation',
  'en_US',
  undefined,
  undefined,
  undefined,
  undefined,
  10,
  10,
);

Exemplo de resposta​

{
  "total": 0,
  "offset": 0,
  "limit": 10,
  "queryLanguage": {
    "resolved": [
      "english"
    ],
    "source": "explicit",
    "candidates": [
      "english"
    ]
  },
  "warnings": [
    "processing_disabled"
  ],
  "items": []
}

Esquema de resposta​

Esquema: IFileSearchResponse

total: number
Número total de arquivos correspondentes.
exemplo: 166

offset: number
Número de registros a pular.
exemplo: 0

limit: number
Número máximo de registros a retornar.
exemplo: 10

queryLanguage: IFileSearchQueryLanguage
Como o idioma da consulta foi determinado.

queryLanguage.resolved: string[]
Configurações de busca textual com as quais a consulta foi executada, por exemplo english.
exemplo: ["english"]

queryLanguage.source: string
Como o idioma foi escolhido: explicit (a partir de langCode), ou script, facet, configured ou fallback quando langCode está vazio.
exemplo: "explicit"

queryLanguage.candidates: string[]
Idiomas considerados.
exemplo: ["english"]

warnings: string[]
Motivos pelos quais o resultado pode estar vazio ou ser aproximado: processing_disabled, query_too_common, query_language_capped, semantic_unavailable, fuzzy_fallback. Vazio quando não há nenhum.

items: IFileSearchItem[]
Arquivos que correspondem à consulta.

items.id: number
ID do arquivo indexado.
exemplo: 1077

items.storageKey: string
Chave do objeto no armazenamento; o link do arquivo é gerado a partir dela.
exemplo: "files/project/file/644/product/db1918c4.pdf"

items.extension: string
Extensão do arquivo.
exemplo: "pdf"

items.title: string | null
Título dos metadados do documento, null quando o documento não tem nenhum.
exemplo: "Microsoft Word - COG Agenda.docx"

items.langCode: string | null
Idioma do conteúdo do arquivo, detectado na indexação.
exemplo: "en"

items.pageCount: number | null
Número de páginas, para formatos paginados.
exemplo: 244

items.rank: number
Relevância da correspondência; a API ordena por ela em ordem decrescente.
exemplo: 0.0971

items.snippet: IFileSearchSnippet | null
O fragmento correspondente.

items.owners: IFileSearchOwner[]
Registros aos quais o arquivo está vinculado, limitados aos que quem faz a chamada pode ver.

items.ownersTotal: number
Quantos registros visíveis para quem faz a chamada referenciam o arquivo.
exemplo: 2