1

Guia de Referência para desenvolvedores (Web Services API)

Versão 2.5 rev.1

(Setembro 2015)

2

Índice

OBJETIVO ........................................................................................................................................ 3

LISTA DE COMANDOS DISPONÍVEIS ........................................................................................... 4

ANEXO A ........................................................................................................................................ 62

ANEXO B ........................................................................................................................................ 63

ANEXO C ........................................................................................................................................ 64

ANEXO D ........................................................................................................................................ 65

ANEXO E ........................................................................................................................................ 66

ANEXO F ........................................................................................................................................ 67

Copyright © 2015 Omneek. Todos os direitos reservados. Nenhuma parte deste documento pode ser

copiada, reproduzida, traduzida ou transmitida por qualquer meio eletrônico ou mecânico, na sua

totalidade ou em parte, sem a prévia autorização escrita.da Omneek que reserva-se o direito de efetuar

alterações sem aviso prévio. A Omneek. não assume nenhuma responsabilidade pelas conseqüências de

quaisquer erros na utilização desta API.

3

Objetivo Esta API permite a desenvolvedores integrarem as funcionalidades semânticas do OmneeK em aplicativos ou páginas web. Para utilizar esta API é necessário ter uma chave válida OmneeK Cloud ou OmneeK Server, bem como acesso liberado ao servidor onde estiver instalado, através do seu endereço IP. Os comandos desta API são enviados como URLs, através de um browser ou qualquer outro tipo de pedido compatível com o padrão XML. Cada um destes comandos integra uma chave de autorização, exclusiva para cada desenvolvedor autorizado.

4

Lista de comandos disponíveis

Gerenciamento de documentos

xml.learn • filename (string) • web_content (1/0) • forced_title (string) • group (int) • group_name (string) • create_group (1/0) • key (string)

Adiciona o documento à fila de aprendizagem, por thread, este método não é indicado para servidores com processamento elevado. Nesse caso utilize o comando “xml.add_document”

xml.learn_url • url (string) • forced_title (string) • group (int) • group_name (string) • create_group (1/0) • key (string)

Aprende o conteúdo de uma URL. Não é possível utilizar com documentos remotos do tipo PDF ou Word (utilize o OmneeK Spider para isso).

xml.add_document • filename (string) • content_type (0/1/2) • forced_title (string) • group_name (string) • key (string)

Adiciona um documento remoto, acessível por http, para aprendizagem.

xml.add_text • text_title (string) • text_external_url (string) • text_body (string) • group_name (string) • key (string)

Aprende o texto nos parâmetros como um documento e adiciona-o ao grupo indicado.

xml.list_documents • start_document (int) • start_description (string) • max_per_page (int) • sort_type (ver Anexo A) • key (string)

Mostra todos os documentos existentes na base de conhecimento. Os parâmetros start_document e start_document_description facilitam a paginação no aplicativo que utiliza o OmneeK.

xml.document_by_origin • origin (string) • key (string)

Retorna o código interno do documento identificado pelo nome de origem.

xml.move_document • document (int) • group_id (int) • key (string)

Move um documento de um grupo para outro.

xml.delete_document • document (int) • key (string)

Apaga documento permanentemente.

5

Gerenciamento de grupos

xml.list_documents_in_group • group (int) • start_document (int) • start_description (string) • max_per_page (int) • sort_type (ver Anexo A) • key (string)

Mostra todos os documentos existentes no grupo especificado Documentos sem grupo têm o valor 0. Os parâmetros start_document e start_document_description facilitam a paginação no aplicativo que utiliza o OmneeK.

xml.get_group_id • group_name (string) • key (string)

Retorna o código interno de um grupo, identificado pelo nome no parâmetro.

xml.move_group • from_group_id (int) • to_group_id (int) • key (string)

Move todos os documentos existentes num grupo, para outro. *Este comando não pode ser utilizado por contas OmneeK Cloud.

xml.new_group • group_name (string) • key (string)

Adiciona um novo grupo à base de conhecimento. *Este comando não pode ser utilizado por contas OmneeK Cloud.

xml.delete_group • group (int) • key (string)

Apaga um grupo existente na base de conhecimento, bem como todos os documentos existentes dentro dele. *Este comando não pode ser utilizado por contas OmneeK Cloud.

xml.delete_all • delete_teached_meanings (1/0) • delete_teached_evaluations (1/0) • key (string)

Apaga toda a base de conhecimento. *Este comando não pode ser utilizado por contas OmneeK Cloud.

xml.total_documents • group (int) • key (string)

Retorna o número de documentos na base de conhecimento ou num grupo

Texto

xml.get_phrase_text • document (int) • phrase_id (int) • key (string)

Retorna o texto da frase identificada pelo código.

6

xml.get_piece_text • document (int) • phrase_id (int) • before_count (int) • after_count (int) • key (string)

Retorna um texto com X frases anteriores, a frase escolhida e Y frases posteriores à frase no parâmetro.

xml.get_full_text • document (int) • key (string) • quickread (1/0)

Retorna o texto completo de um documento.

Pesquisas

xml.search_for_phrase • document (int) • group (int) • search (string) • search_profile • max_results (int) • min_score (int) • exclude_titles (1/0) • key (string)

Pesquisa um texto dentro da base de conhecimento, retornando as FRASES relacionadas. Podem ser aplicados filtros por grupo e por documento.

xml.more_results • return_code (int) • from_result (int) • max_per_page (int)

Permite obter mais resultados de uma busca. Útil para paginação.

xml.intersects • document (int) • group (int) • search1 (string) • search2 (string) • search_profile1 (ver Anexo B) • search_profile2 (ver Anexo B) • key (string)

Realiza uma pesquisa onde as FRASES dos resultados têm que estar relacionadas com ambos os textos apresentados.

xml.nested_search • document (int) • group (int) • search1 (string) • search2 (string) • search_profile1 (ver Anexo B) • search_profile2 (ver Anexo B) • criteria (ver Anexo C) • max_per_page (int) • key (string)

Realiza duas buscas em sequência, sendo que a segunda será apenas realizada sobre os resultados da primeira. Retorna FRASES.

xml.search_for_document • group (int) • search (string) • max_results (int) • search_profile (ver Anexo B) • min_score (int) • max_results (int) • key (string)

Pesquisa os documentos que possuem conteúdo relacionado com o texto da busca. Retorna DOCUMENTOS.

7

xml.fast_search_for_document • group (int) • search (string) • max_results (int) • search_profile (ver Anexo B) • min_score (int) • max_results (int) • key (string)

Pesquisa rapidamente os documentos que possuem conteúdo relacionado com o texto da busca. Retorna DOCUMENTOS.

Respostas

xml.ask • document (int) • group (int) • question (string) • search_profile (ver Anexo B) • complementary_text_type (ver Anexo

E) • min_score (int) • no_repettions (1/0) • highlight (1/0) • key (string)

Procura respostas e frases relacionadas com o texto. O texto pode ser colocado em forma de pergunta ou busca simples. Retorna frases, títulos, seções ou parágrafos relacionados com a busca.

xml.generate_search_from_question

• question (string) Retorna o texto a ser pesquisado, para encontrar os documentos onde será mais provável encontrar a resposta à questão colocada. Deve ser utilizado quando a base documental é grande, de modo a reduzir o escopo onde a resposta será procurada.

xml.is_question • query (string) • key (string)

Avalia se uma frase é uma questão

Inteligência Artificial

xml.list_inferences • document (int) • query (string) • key (string)

Mostra lista de inferências automáticas existentes dentro de um texto

Resumos

xml.summarize_document • document (int) • depth (int) • search_profile (ver Anexo B) • key (string)

Resume o documento especificado, encontrando as frases mais relevantes do seu conteúdo.

8

xml.summarize_subject • document (int) • group (int) • depth (int) • subject (string) • search_profile (ver Anexo B) • key (string)

Realiza um resumo do assunto ou entidade especificado, procurando frases relevantes sobre um documento, grupo ou conjunto de documentos.

Extração de tags

xml.extract_tags • document (int) • filename (string) • depth (int) • add_plurals (1/0) • from_phrase_id (int) • to_phrase_id (int) • key (string)

Extrai as palavras mais importantes num documento. Indicado para criar uma nuvem de tags automática.

xml.tag_cloud • process_text (string) • max_tags (int) • direct_only (1/0) • key (string)

Identifica os temas mais importantes num texto submetido diretamente pela URL.

xml.extract_tag_connected_entities

• document (int) • filename (string) • depth (int) • seed (string) • key (string)

Identifica as tags mais ligadas com um tema, dentro de um documento

Comparação de documentos

xml.compare_docs_version • document1 (int) • document2 (int) • filename1 (string) • filename2 (string) • detail_section (1/0) • detail_phrase (1/0) • key (string)

Produz um relatório de comparação de documentos, que permite complementar versões do mesmo documento, especificando as alterações existentes de um para o outro.

Gerar questões

xml.questionize_document • document (int) • depth (int) • search_profile (ver Anexo B) • key (string)

* funcionalidade experimental em desenvolvimento

xml.questionize_subject • document (int) • group (int) • depth (int) • subject (string) • search_profile (ver Anexo B) • key (string)

* funcionalidade experimental em desenvolvimento

9

Métricas de documentos

xml.outline • document (int) • filename (string) • class (ver Anexo F) • depth (int) • key (string)

Para cada seção existente num documengto, permite mostrar: tags, resumos

xml.metrics • document (int) • filename (string) • key (string)

Produz um índice automático, mostrando as seções de um documento.

Gerenciamento de usuários

xml.check_user • username (string) • password (string) • key (string)

Verifica a senha de um usuário.

xml.create_user • supervisor_username (string) • supervisor_password (string) • username (string) • password (string) • email (string) • is_supervisor (1/0) • key (string)

Cria um novo usuário. Este comando apenas pode ser executado por usuário supervisor.

xml.list_users • username (string) • password (string) • key (string)

Mostra a lista dos usuários existentes. Apenas um supervisor pode ver a lista completa.

xml.change_password • username (string) • old_password (string) • new_password (string) • key (string)

Altera a senha de um usuário.

xml.delete_user • supervisor_username (string) • supervisor_password (string) • delete_username (string) • key (string)

Apaga um usuário existente. Apenas um supervisor pode executar este comando.

Relatórios e estatísticas

xml_no_answers • days_before (int) • group_id (int) • key (string)

Retorna um relatório com as pesquisas (por ask.xml) que não tiveram resultados.

xml.stats • days_before (int) • group_id (int) • max_results (int) • key (string)

Retorna um relatório com as palavras mais pesquisadas no periodo indicado.

10

xml.queries_for_word • days_before (int) • group_id (int) • word_text (string) • key (string)

Mostra um relatório com a lista de pesquisas realizadas, onde aparece a palavra indicada. Apenas válido para palavras fora do léxico.

xml.queries_for_token • days_before (int) • group_id (int) • token_id (int) • key (string)

Mostra um relatório com a lista de pesquisas realizadas, onde aparece a palavra indicada. Apenas válido para palavras do léxico.

xml.flush_stats • days_before (int) • group_id (int) • key (string)

Limpa as estatísticas existentes.

xml.increment_rank_score • document (int) • key (string)

Aumenta a popularidade de um documento da base de conhecimento. Habitualmente este comando é utilizado antes de abrir um resultado do comando “xml.search_best_doc”.

11

xml.learn Descrição Adiciona o documento à fila de aprendizagem, por thread, este método não é indicado para servidores com processamento elevado. Apenas aceita documento locais. Para outros casos utilize o comando “xml.add_document”.

Método: xml.learn

Exemplo: http://localhost/xml.learn?filename=readme.txt&web_content=0&forced_title=teste&save_evaluations=0&group=0&group_name=meu%20grupo&create_group=1&key=aaaBBBcccDDD

Parâmetros de entrada: filename: (string) nome completo do arquivo para aprender. Apenas podem ser colocados arquivos com caminho de rede válido. URLs não serão processados. web_content: (1/0) parâmetro que indica se é um arquivo gravado da web (ex: uma página HTML). forced_title: (string) permite especificar um título para o documento. Se nenhum for providenciado, o sistema tentará encontrar um dentro do documento. group: (int) código do grupo onde o documento deverá ser gravado. group_name: (string) nome do grupo onde o documento será adicionado. Se o parâmetro “group” estiver preenchido “group_name” será ignorado. create_group: (1/0) cria um novo grupo com o nome “group_name”, se ainda não existir key: (string) chave de autorização

Retorna XML: <omneek_learn> <documents_in_queue> (1) <error_message> (2) </omneek_learn> (1) - número de documentos à frente na fila de

aprendizagem (2) - mensagem de erro ou de sucesso

12

xml.learn_url Descrição Aprende o conteúdo de uma URL, extraindo o texto legível e criando um documento que adiciona na base de conhecimento. Não é possível utilizar com documentos remotos do tipo PDF, Word, etc. Este comando deve ser utilizado com precaução, em servidores com alta demanda de pedidos ao OmneeK, podendo ter impacto significativo no processamento durante a aprendizagem. O OmneeK Server deverá ser utilizado para recolher conteúdo frequente da web.

Método: xml.learn_url

Exemplo: http://localhost/xml.learn_url?url=http%3A%2F%2Fomneek.com%2Ftest.html%0A&forced_title=teste&group=0&group_name=meu%20grupo&create_group=1&key=aaaBBBcccDDD

Parâmetros de entrada: url: (string) página onde está o conteúdo a aprender. Colocar a URL completa, incluindo o “http://” forced_title: (string) permite especificar um título para o documento. Se nenhum for providenciado, o sistema tentará encontrar um dentro do documento. group: (int) código do grupo onde o documento deverá ser gravado. group_name: (string) nome do grupo onde o documento será adicionado. Se o parâmetro “group” estiver preenchido “group_name” será ignorado. create_group: (1/0) cria um novo grupo com o nome “group_name”, se ainda não existir key: (string) chave de autorização

Retorna XML: <document> <document_id> (1) </document> (1) - código atribuído ao novo documento, gerado a

partir da URL

13

xml.add_document Descrição Adiciona um documento remoto à pasta monitorizada pelo OmneeK Server, de modo a ser aprendido. O processo realiza o download do documento especificado, extrai o texto existente e coloca-o na fila de aprendizagem do OmneeK Learner. O tempo até ser aprendido depende do número de documentos já existentes na fila.

Método: xml.add_document

Exemplo: http://localhost/xml.add_document?filename=http%3A%2F%2Fomneek.com%2Ftest.pdf%0A&forced_title=teste&group=0&group_name=meu%20grupo&content_type=2create_group=1&key=aaaBBBcccDDD

Parâmetros de entrada: filename: (string) página onde está o conteúdo a aprender. Colocar a URL completa, incluindo o “http://” content_type: (0/1/2) tipo de conteúdo: - (0) arquivo web (html, asp, etc) - (1) arquivo normal (pdf,doc,txt) - (2) arquivo com títulos de seções

precedidos com “->” forced_title: (string) permite especificar um título para o documento. Se nenhum for providenciado, o sistema tentará encontrar um dentro do documento. group_name: (string) nome do grupo onde o documento será adicionado. Se o parâmetro “group” estiver preenchido “group_name” será ignorado. key: (string) chave de autorização

Retorna XML: <omneek_learn> <error_message> (1) </omneek_learn> (1) - mensagem de erro ou de sucesso

14

xml.add_text Descrição Adiciona um texto à base de conhecimento. O título, link externo e conteúdo do novo documento, são enviados diretamente como parâmetros. O novo documento é adicionado ao grupo especificado. Este comando é particularmente útil para adicionar conteúdo externo aos resultados das buscas. Para isto basta colocar em “text_body” os assuntos que são relevantes para este documento e no link a url externa.

Método: xml.add_text

Exemplo: http://localhost/xml.add_text?text_title=titulo%20de%20teste&title_external_url=http%3A%2F%2Fomneek.com%2Ftest.pdf&text_body=era%20uma%20vez...0&group_name=meu%20grupo&key=aaaBBBcccDDD

Parâmetros de entrada: text_title: (string) título do novo documento text_external_url: (string) link para abrir uma url externa, associada com este texto. Não tem que ser necessariamente o conteúdo do texto adicionado. Pode ser apenas relacionado e em text_body enviar palavras chave. text_body: (string) Texto do novo documento, ou palavras que o identifiquem em buscas, de modo a poder utilizar este resultado para abrir o link especificado. group_name: (string) nome do grupo onde o documento será adicionado. Se o parâmetro “group” estiver preenchido “group_name” será ignorado. key: (string) chave de autorização

Retorna XML: <omneek_learn> <error_message> (1) </omneek_learn> (1) - mensagem de erro ou de sucesso

15

xml.list_documents Descrição Mostra a lista completa de documentos disponíveis na base de conhecimento. Este comando permite colocar o número inicial do documento ou o seu título. Em conjunto com o tipo de ordenação, é possível coordenar paginação no aplicativo. O tipo de ordenação pode ser consultado no Anexo A.

Método: xml.list_documents

Exemplo: http://localhost/xml.list_documents?start_document=0&max_per_page=25&sort_type=0%20grupo&key=aaaBBBcccDDD

Parâmetros de entrada: start_document: (int) código do último documento mostrado em lista. Para mostrar desde o início utilizar o código 0. Necessário utilizar quando o tipo de ordenação tem por base a data de aprendizagem (crescente ou decrescente) start_description: (string) título do último documento mostrado. Para mostrar desde o início, deixar em branco. Necessário utilizar quando o tipo de ordenação tem por base ordem alfabética de título (crescente ou decrescente) max_per_page: (int) Número máximo de documentos a mostrar. Para paginação é necessário guardar o último documento mostrado (código ou título, dependendo do tipo de ordenação) sort_type: (ver Anexo A) código do tipo de ordenação pretendido key: (string) chave de autorização

Retorna XML: <documents> <document> <id> (1) <family_id> (2) <description> (3) <learning_date> (4) <classification> (5) <origin> (6) </document> </documents> (1) - código do documento (2) - código do grupo do documento (3) - título ou descritivo do documento (4) - data e hora em que foi indexado este

documento (5) - tipo de conteúdo (* funcionalidade

experimental) (6) - origem (url ou nome do arquivo)

16

xml.document_by_origin Descrição Retorna o código do documento indexado a partir da origem especificada. A origem pode representar uma URL ou o nome de um arquivo.

Método: xml.document_by_origin

Exemplo: http://localhost/xml.document_by_origin?origin=readme.txt&key=aaaBBBcccDDD

Parâmetros de entrada: origin: (string) nome do arquivo ou url que deu origem a este documento key: (string) chave de autorização

Retorna XML: <document> <document_id> (1) <document_title> (2) </document> (1) - código do documento (2) - título ou descritivo do documento

17

xml.move_document Descrição Move o documento para um grupo, não importando se ele já pertence a um grupo ou não. Dependendo do tamanho do documento, esta operação pode ter impacto no processamento de pesquisas, pelo que deve ser realizada em horários de menor demanda.

Método: xml.move_document

Exemplo: http://localhost/xml.move_document?document=23&group_id=2&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento a mover. group_id: (int) código do grupo onde o documento deverá ser gravado. key: (string) chave de autorização

Retorna XML: <result> <new_group> (1) </result> (1) - OK ou ERROR

18

xml.delete_document Descrição Apaga o documento especificado. Esta operação não poderá ser anulada. Dependendo do tamanho do documento, esta operação pode ter impacto no processamento de pesquisas, pelo que deve ser realizada em horários de menor demanda.

Método: xml.delete_document

Exemplo: http://localhost/xml.delete_document?document=23key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento a apagar. key: (string) chave de autorização

Retorna XML: <result> <delete> (1) </result> (1) - OK ou ERROR

19

xml.list_documents_in_group Descrição Comando idêntico ao “xml.list_documents”, mas restrito a um grupo.

Método: xml.list_documents_in_group

Exemplo: http://localhost/xml.list_documents_in_group?group=2&start_document=0&max_per_page=25&sort_type=0%20grupo&key=aaaBBBcccDDD

Parâmetros de entrada: group: (int) código do grupo onde pertencem os documentos. start_document: (int) código do último documento mostrado em lista. Para mostrar desde o início utilizar o código 0. Necessário utilizar quando o tipo de ordenação tem por base a data de aprendizagem (crescente ou decrescente) start_description: (string) título do último documento mostrado. Para mostrar desde o início, deixar em branco. Necessário utilizar quando o tipo de ordenação tem por base ordem alfabética de título (crescente ou decrescente) max_per_page: (int) Número máximo de documentos a mostrar. Para paginação é necessário guardar o último documento mostrado (código ou título, dependendo do tipo de ordenação) sort_type: (ver Anexo A) código do tipo de ordenação pretendido key: (string) chave de autorização

Retorna XML: <documents> <document> <id> (1) <family_id> (2) <description> (3) <learning_date> (4) <classification> (5) <total_phrases> (6) <origin> (7) <link> (8) </document> </documents> (1) - código do documento (2) - código do grupo do documento (3) - título ou descritivo do documento (4) - data e hora em que foi indexado (5) - tipo de conteúdo (* funcionalidade

experimental) (6) - número total de frases (7) - origem (url ou nome do arquivo de onde foi

indexado (8) - link externo para a url ou arquivo onde pode

ser aberto o documento

20

xml.get_group_id Descrição Retorna o código do grupo correspondente ao nome de grupo indicado.

Método: xml.get_group_id

Exemplo: http://localhost/xml.get_group_id?group_name=escrituras&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento a apagar. key: (string) chave de autorização

Retorna XML: <group> <id> (1) </group> (1) - código que identifica o grupo pretendido.

Retorna o valor “0” se não encontrar.

21

xml.move_group Descrição Comando para mover todos os documentos de um grupo para outro. Esta operação deve ser realizada num momento em que não exista demanda significativa para o servidor. A framework OmneeK tentará amenizar o impacto, mas se o número de documentos for significativo esta poderá ser uma operação muito prolongada, podendo demorar vários minutos, uma vez que implica a substituição da maioria do índices no banco de dados.

Método: xml.move_group

Exemplo: http://localhost/xml.move_group?from_group_id=1&to_group_id=2&key=aaaBBBcccDDD

Parâmetros de entrada: from_group_id: (int) código grupo origem to_group_id: (int) código grupo destino key: (string) chave de autorização

Retorna XML: <result> <new_group> (1) </result> (1) - OK ou ERROR

22

xml.new_group Descrição Este comando permite criar um novo grupo dentro da base de conhecimento. Se já existir um grupo com o mesmo nome, o código do grupo existente será retornado.

Método: xml.new_group

Exemplo: http://localhost/xml.new_group?group_name=teste&key=aaaBBBcccDDD

Parâmetros de entrada: group_name: (string) nome do novo grupo key: (string) chave de autorização

Retorna XML: <result> <new_group> (1) </result> (1) - OK ou ERROR

23

xml.delete_group Descrição Comando para apagar o grupo especificado, bem como todos os documentos existentes nesse grupo. Esta operação deve ser realizada num momento em que não exista demanda significativa para o servidor. A framework OmneeK tentará amenizar o impacto, mas se o número de documentos for significativo esta poderá ser uma operação muito prolongada, podendo demorar vários minutos, uma vez que implica a substituição da maioria do índices no banco de dados.

Método: xml.delete_group

Exemplo: http://localhost/xml.delete_group?group=1&key=aaaBBBcccDDD

Parâmetros de entrada: group: (int) código grupo a apagar key: (string) chave de autorização

Retorna XML: <result> <delete> (1) </result> (1) - OK ou ERROR

24

xml.delete_all Descrição Comando para apagar todos os grupos e todos os documentos existentes na base de conhecimento. Opcionalmente é possível também apagar o conhecimento marcado com permanente, recolhido dos documentos indexados e as palavras marcadas com negativas ou positivas, para a análise de sentimento. Esta operação poderá demorar várias horas. Opcionalmente, um DBA poderá optar por apagar o banco de dados e recriar a sua estrutura. As contas de operador e chaves de utilização existentes serão perdidas, mas a operação é muito mais rápida.

Método: xml.delete_all

Exemplo: http://localhost/xml.delete_all?delete_teached_meanings=1&delete_teached_evaluations=0&key=aaaBBBcccDDD

Parâmetros de entrada: delete_teached_meanings: (1/0) apaga ou não o conhecimento permanente recolhido das indexações ou manualmente ensinado delete_teached_evaluations: (1/0) apaga ou não as palavras definidas manualmente como negativas ou positivas key: (string) chave de autorização

Retorna XML: <result> <delete> (1) </result> (1) - OK ou ERROR

25

xml.total_documents Descrição Comando para obter o número total de documentos em toda a base de conhecimento ou o num grupo. Deixar o valor de “group” com 0 para obter todos.

Método: xml.total_documents

Exemplo: http://localhost/xml.total_documents?group=0&key=aaaBBBcccDDD

Parâmetros de entrada: group: (int) código do grupo key: (string) chave de autorização

Retorna XML: <omneek> <groups> <total_group> (1) <total_all> (2) <total_phrases> (3) </groups> </omneek> (1) - total de documentos no grupo (0 se não existir

grupo) (2) - total de documentos na base de conhecimento (3) - total de frases na base de conhecimento

26

xml.get_phrase_text Descrição Este comando permite obter o texto correspondente a uma frase.

Método: xml.get_phrase_text

Exemplo: http://localhost/xml.get_phrase_text?document=1&phrase_id=67&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento que contém a frase phrase_id: (int) código interno da frase key: (string) chave de autorização

Retorna XML: <phrase> <text> (1) </phrase> (1) - texto da frase

27

xml.get_piece_text Descrição Retorna um texto com X frases anteriores, a frase escolhida e Y frases posteriores à frase no parâmetro. Se não existirem frases suficientes, antes ou depois, será retornado até ao limite.

Método: xml.get_piece_text

Exemplo: http://localhost/xml.get_piece_text?document=1&phrase_id=67&before_count=5&after_count=5&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento que contém a frase phrase_id: (int) código interno da frase before_count: (int) número de frases antes after_count: (int) número de frase após key: (string) chave de autorização

Retorna XML: <piece> <text> (1) </piece> (1) - texto completo

28

xml.get_full_text Descrição Este comando permite obter todo o texto de um documento.

Método: xml.get_full_text

Exemplo: http://localhost/xml.get_full_text?document=1&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento key: (string) chave de autorização quickread: (1/0) ativar compressão de frases

Retorna XML: <phrases> <phrase> <id> (1) <phrase_text> (2) <evaluation> (3) </phrase> </phrases> (1) - código identificador da frase no documento (2) - texto da frase (3) - avaliação (0 = neutra; 1 = positiva; -1 =

negativa). Este valor apenas será preenchido se o documento tiver sido indexado com a opção “save_evaluations”.

29

xml.search_for_phrase Descrição Pesquisa o texto especificado, retornando as frases mais relacionadas, de acordo com o perfil de busca pretendido. É possível limitar o escopo desta pesquisa a um ou mais grupos de documentos ou a um conjunto limitado de documentos. Para uma base de conhecimento muito extensa, deverá ser sempre utilizado o comando “xml.search_for_document”.

Método: xml.search_for_phrase

Exemplo: http://localhost/xml.search_for_phrase?document=2,3,4&search=omneek%20clientes&search_profile=0&max_results=25&min_score=20&exclude_titles=0&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int,int...) conjunto de documentos onde será realizada a pesquisa. Os códigos devem ser separados por vírgulas. Se não for especificado nenhum documento, será utilizado o parâmetro group ou toda a base de conhecimento group: (int,int...) conjunto de documentos onde será realizada a pesquisa search: (string) texto a pesquisar search_profile: (ver Anexo B) código do perfil de busca max_results: (int) número máximo de resultados min_score: (int) valor mínimo para considerar um resultado. Os valores de pontuação variam entre 0 e 100. exclude_titles: (1/0) o valor 1 exclui os títulos de aparecerem como resultados boost_titles_score: (1/0) aumentar o score dos títulos e sub-títulos para aparecerem mais acima na lista de resultados

key: (string) chave de autorização

Retorna XML: <omneek_search> <total_results> (1) <search_time> (2) <search_results> <search_result> <order> (3) <document_id> (4) <phrase_id> (5) <score> (6) <phrase_text> (7) <knowledge_description> (8) <knowledge_origin> (9) <knowledge_link> (10) <evaluation> (11) <nearest_title> (12) </search_result> </search_results> </omneek_search> (1) - total de resultados da busca (2) - tempo de busca (3) - posição da frase na ordem de resultados (4) - código do documento onde foi encontrada a frase (5) - código da frase, dentro do documento (6) - score obtido por esta frase, relativo à relevância

sobre o texto pesquisado (7) - texto da frase (8) - título do documento onde foi encontrada a frase (9) - nome do arquivo que foi indexado e onde foi

encontrada a frase (10) - link (url ou nome do arquivo) externo para abrir

o documento original, onde foi encontrada a frase (11) - sentimento (0 = neutro; 1 = positivo; -1= negativo) (12) - texto do título mais próximo acima da frase

resultado

30

xml.more_results Descrição Permite obter mais resultados para a busca realizada. Terá que ser utilizado como parâmetro o código retornado em “return_code”, no comando “xml.search”. Este comando é útil para facilitar a paginação de resultados.

Método: xml.more_results

Exemplo: http://localhost/xml.more_results?result_code=19&from_result=26&max_per_page=25

Parâmetros de entrada: result_code: (int) código resultante do comando “xml.search” from_result: (int) número de ordem do primeiro resultado a aparecer max_per_page: (int) número máximo de resultados.

<search_results> <search_result> <order> (1) <document_id> (2) <phrase_id> (3) <score> (4) <phrase_text> (5) <knowledge_description> (6) <knowledge_origin> (7) <knowledge_link> (8) </search_result> </search_results> (1) - posição da frase na ordem de resultados (2) - código do documento onde foi encontrada a

frase (3) - código da frase, dentro do documento (4) - score obtido por esta frase, relativo à relevância

sobre o texto pesquisado (5) - texto da frase (6) - título do documento onde foi encontrada a

frase (7) - nome do arquivo que foi indexado e onde foi

encontrada a frase (8) - link (url ou nome do arquivo) externo para

abrir o documento original, onde foi encontrada a frase

31

xml.intersects Descrição Este comando permite determinar rapidamente se um documento possui resultados para duas buscas. O comando não retorna os resultados. Apenas se elas são relevantes ou não para o documento especificado. Deve ser utilizado para construir o escopo de uma busca, sem pesquisar sobre toda a base, encontrando os documentos que melhor respondem. O comando “xml.search_best_doc” é semelhante, mas apenas para uma pesquisa.

Método: xml.intersects

Exemplo: http://localhost/xml.intersects?document=344&search1=hoje&search2=sol&search_profile1=0&search_profile2=5&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento search1: (string) texto da pesquisa número 1 search2: (string) texto da pesquisa número 2 search_profile1: (ver Anexo B) código do perfil para a pesquisa número 1 search_profile2: (ver Anexo B) código do perfil para a pesquisa número 2 key: (string) chave de autorização

<intersection> <intersection_result> (1) <search1_evaluation> (2) <search2_evaluation> (3) </intersection> (1) - valor “1” se o documento possui resultados

para ambas as buscas. “0” se não. (2) - avaliação da busca número 1 (3) - avaliação da busca número 2

32

xml.nested_search Descrição Realiza duas buscas em sequência, sendo que a segunda será apenas realizada sobre os resultados da primeira. Utilizando o valor do parâmetro “criteria” é possível adicionar os resultados de ambas as buscas, excluir os resultados da segunda, se não aparecerem na primeira. O Anexo C possui a lista de valores possíveis.

Método: xml.nested_search

Exemplo: http://localhost/xml.nested_search?document=344&search1=hoje&search2=sol&search_profile1=0&search_profile2=5&max_per_page=25&criteria=1&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int,int...) lista de códigos de documentos onde será realizada a pesquisa group: (int,int...) código do grupo. Pode ser utilizada uma lista de grupos, separados por vírgulas search1: (string) texto da pesquisa número 1 search2: (string) texto da pesquisa número 2 search_profile1: (ver Anexo B) código do perfil para a pesquisa número 1 search_profile2: (ver Anexo B) código do perfil para a pesquisa número 2 criteria: (ver Anexo C) código de inclusão ou exclusão de resultados, perante as duas pesquisas max_per_page: (int) número máximo de resultados. Mais resultados podem ser obtidos com o comando “xml.more_results” key: (string) chave de autorização

<omneek_search> <search_details> <return_code> (1) <total_results> (2) <search_time> (3) <search_details> <search_results> <search_result> <order> (4) <document_id> (5) <phrase_id> (6) <score> (7) <phrase_text> (8) <knowledge_description> (9) <knowledge_origin> (10) <knowledge_link> (11) </search_result> </search_results> </omneek_search> (1) - código que identifica esta busca. Pode ser

utilizado juntamente com o comando “xml.more_results”

(2) - total de resultados da busca (3) - tempo de busca (4) - posição da frase na ordem de resultados (5) - código do documento onde foi encontrada a

frase (6) - código da frase, dentro do documento (7) - score obtido por esta frase, relativo à relevância

sobre o texto pesquisado (8) - texto da frase (9) - título do documento onde foi encontrada a

frase (10)-nome do arquivo que foi indexado e onde foi encontrada a frase (11)- link (url ou nome do arquivo) externo para abrir o documento original, onde foi encontrada a frase

33

xml.search_for_document Descrição Este comando permite pesquisar e encontrar a lista dos documentos mais relevantes para um ou mais temas, identificando quais os que têm relevância para a busca pretendida. Este comando não retorna frases. Quando um documento for selecionado sobre a lista de resultados, poderá ser realizada uma busca por frase com o comando “xml.search_for_phrase”.

Método: xml.search_for_document

Exemplo: http://localhost/xml.search_for_document?group=3,4,6&search=hoje%20sol&search_profile=1&max_results=20&key=aaaBBBcccDDD

Parâmetros de entrada: group: (int,int...) código do grupo. Pode ser utilizada uma lista de grupos, separados por vírgulas search: (string) texto para pesquisar max_results: (int) número máximo de resultados. Não existe paginação com este comando. search_profile: (ver Anexo B) código do perfil para a pesquisa min_score: (int) score mínimo necessário para aceitar um documento como relevante. O score varia de 0 a 100. max_results: (int) número máximo de resultados, se a busca por frase for necessária above_document_id: (int) buscar em documentos com document_id acima do valor do parâmetro key: (string) chave de autorização

<omneek_search_for_document> <total_results> (1) <search_results> <search_result> <document_id> (2) <knowledge_description> (3) <knowledge_origin> (4) <knowledge_date> (5) <result_score> (6) </search_result> </search_results> </omneek_search_for_document> (1) - total de resultados da busca (2) - código do documento (3) - título do documento (4) - nome do arquivo que foi indexado (5) - data de indexação do documento (6) – score do resultado (0..100)

34

xml.fast_search_for_document Descrição Este comando permite pesquisar rapidamente sobre uma grande quantidade de documentos, identificando quais os que têm relevância para a busca pretendida. Este comando não retorna frases. Quando um documento for selecionado sobre a lista de resultados, poderá ser realizada uma busca por frase com o comando “xml.search_for_phrase”. Para uma base documental grande, com centenas ou milhares de documentos, este é o comando preferencial para realizar buscas.

Método: xml.search_for_document

Exemplo: http://localhost/xml.fast_search_for_document?group=3,4,6&search=hoje%20sol&search_profile=1&max_results=20&key=aaaBBBcccDDD

Parâmetros de entrada: group: (int,int...) código do grupo. Pode ser utilizada uma lista de grupos, separados por vírgulas search: (string) texto para pesquisar max_results: (int) número máximo de resultados. Não existe paginação com este comando. search_profile: (ver Anexo B) código do perfil para a pesquisa min_score: (int) score mínimo necessário para aceitar um documento como relevante. O score varia de 0 a 100. max_results: (int) número máximo de resultados, se a busca por frase for necessária above_document_id: (int) buscar em documentos com document_id acima do valor do parâmetro key: (string) chave de autorização

<omneek_search_for_document> <total_results> (1) <search_results> <search_result> <document_id> (2) <knowledge_description> (3) <knowledge_origin> (4) <knowledge_date> (5) <result_class> (6) </search_result> </search_results> </omneek_search_for_document> (1)- total de resultados da busca (2)- código do documento (3)- título do documento (4)- nome do arquivo que foi indexado (5) - data de indexação do documento (6)- classe do resultado: (1=existem frases totalmente ligadas; 2=documento diretamente relevante; 3=existem frases ligadas apenas semanticamente; 4=documento semanticamente relevante)

35

xml.ask Descrição Comando para procurar respostas na base de conhecimento. Na sua execução o OmneeK começará por classificar o texto a pesquisar como uma questão ou uma busca simples. Se for classificado como uma questão será feito um parsing automático, excluindo das palavras chave os literais desnecessários como “o que”, “como”, etc. Os resultados são agrupados em respostas encontradas ou frases com possíveis respostas. Se o texto a pesquisar não for uma questão, apenas aparecerão resultados nas possíveis respostas.

Método: xml.ask

Exemplo: http://localhost/xml.ask?group=3,4,6&question=como%20calcular%20o%20frete%3F&search_profile=0&comlementary_text_type=11&min_score=30&no_repetitions=1&0sol&highlight=1&key=aaaBBBcccDDD

36

Parâmetros de entrada: document: (int,int...) lista de códigos de documentos onde será realizada a pesquisa group: (int,int...) código do grupo. Pode ser utilizada uma lista de grupos, separados por vírgulas question: (string) texto para pesquisar em forma de palavras chave ou questão search_before_looking_for_answer: (1/0) limitar procura de respostas apenas aos documentos mais significativos. Acelera respostas em bases de conhecimento grandes. complementary_text_type: (ver Anexo E) permite especificar o tipo de texto a apresentar nas possíveis respostas encontradas. Pode ser configurado o título, a frase, o parágrafo, etc. no_repetitions: (1/0) este parâmetro funciona em conjunto com o “complementary_text_type” e permite excluir repetições da lista de resultados. Por exemplo quando o tipo de texto é uma seção e várias frases da mesma seção são possíveis respostas highlight: (1/0) opção para adicionar uma tag HTML que sublinha a amarelo a frase relevante dentro do texto apresentado max_phrases_to_use: (int) número de frases máximo onde procurar resposta max_phrases_to_use: (int) número de frases máximo onde procurar resposta max_documents_used_to_extract_phrases: (int) usado em conjunto com search_before_looking_for_answer define o número máximo de documentos a utilizar depois da busca de documentos show_section_text: (1/0) mostrar ou não o texto da seção onde a resposta foi encontrada exclude_titles: (1/0) excluir títulos e sub-títulos da lista de resultados boost_titles_score: (1/0) aumentar o score dos títulos e sub-títulos para aparecerem mais acima na lista de resultados key: (string) chave de autorização

<omneek_ask> <answers> <answer> <document_id> (1) <phrase_id> (2) <generated_answer_text> (3) <original_phrase_text> (4) <complementary_text> (5) <section_text> (6) <answer_link> (7) <answer_level> (8) <document_description> (9) <document_link> (10) </answer> </answers> <possible_answers> <possible_answer> <possible_answer_document_id> (11) <possible_answer_phrase_id> (12) <possible_answer_phrase_text> (13) <possible_answer_complementary_text> (14) <possible_answer_section_text> (15) <possible_answer_link> (16) <possible_answer_score> (17) <possible_answer_document_description> (18) <possible_answer_document_link> (19) </possible_answer> </possible_answers> </omneek_ask> (1) - código do documento onde foi encontrada a resposta (2) - código da frase dentro do documento, onde foi encontrada a resposta (3) - resposta direta (*funcionalidade experimental) (4) - frase completa onde foi encontrada a resposta (5) - texto complementar de acordo com a opção

“complementary_text_type” (6) - texto completo da seção onde está a frase (útil para popups) (7) - link relacionado com a resposta (*funcionalidade experimental) (8) - nível de confiança da resposta (9) - título do documento onde foi encontrada a resposta (10) - link externo para o documento onde foi indexado o documento da

resposta (11) - código do documento onde foi encontrada a possível resposta (12) - código da frase dentro do documento, onde foi encontrada a

possível resposta (13) - frase completa da possível resposta (14) - texto complementar de acordo com a opção

“complementary_text_type” (15) - texto completo da seção onde está a frase (útil para popups) (16) - link relacionado com a resposta (*funcionalidade experimental) (17) - score obtido por esta possível resposta (18) - título do documento onde foi encontrada a resposta (19) - link externo para o documento onde foi indexado o documento da

possível resposta

37

xml.generate_search_from_question Descrição Comando para gerar o texto relevante para uma pesquisa, com base numa questão. Este texto pode ser utilizado em conjunto com o comando xml.search_for_document, para reduzir o escopo onde o xml.ask será aplicado.

Método: xml.generate_search_from_question

Exemplo: http://localhost/xml.generate_search_from_question?question=onde%20encontro%20a%20%20vossa%20sede?

Parâmetros de entrada: question: (string) texto da questão

<omneek_search_from_question> <final_search> (1) </omneek_search_from_question> (1) - texto para utilizar na busca

38

xml.is_question Descrição Este método avalia se uma frase é uma questão ou não. Mesmo que a frase não termine num ponto de interrogação, o resultado pode ser positivo.

Método: xml.is_question

Exemplo: http://localhost/xml.generate_search_from_question?question=onde%20encontro%20a%20%20vossa%20sede?

Parâmetros de entrada: query: (string) texto para avaliar key: (string) chave de autorização

<omneek> <is_question> (1) </omneek> (1) - retorna o valor 1 se a query corresponder a

uma questão ou 0 se não.

39

xml.summarize_document Descrição Resume um documento, retornando o número de frases máximo pretendido pelo usuário. Os resumos são criados automaticamente de acordo com a dimensão e número de seções existentes no documento. São retornadas as frases completas mais relevantes, bem como as frases submetidas a um algoritmo de compressão, para resumos mais compactos.

Método: xml.summarize_document

Exemplo: http://localhost/xml.summarize_document?document=19&depth=5&search_profile=0&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento. Apenas é permitido um documento neste comando depth: (int) número máximo de frases no resumo. Pode não ser encontrado um número suficiente de frases relevantes para o assunto do documento, para completar este número. A determinação do assunto é automática. search_profile: (ver Anexo B) código do perfil para a pesquisa de frases relevantes use_title: (1/0) Utilizar, ou não, o título como parte importante para gerar tags key: (string) chave de autorização

<omneek_summary> <generated_results> <generated_result> <document_id> (1) <phrase_id> (2) <generated_phrase_text> (3) </generated_result> </generated_results> <original_results> <original_result> <document_id> (4) <phrase_id> (5) <oroginal_phrase_text> (6) </original_result> </original_results> <document_tags> <tag_string> (7) </original_result> </documents_tags> </omneek_summary> (1) - código do documento da frase (2) - código da frase dentro do documento (3) - texto da frase, depois de submetido ao

algoritmo de compressão (4) - código do documento da frase (5) - código da frase dentro do documento (6) - texto original da frase (7) - lista de tags mais relevantes para o documento,

separadas pelo char "|"

40

xml.summarize_subject Descrição Resume um assunto, procurando frases relevantes sobre ele sobre um grupo de documentos ou toda a base de conhecimento. A pesquisa realizada é diferente da busca “xml.ask”, uma vez que privilegia frases que definam o assunto e não apenas ocorrências.

Método: xml.summarize_subject

Exemplo: http://localhost/xml.summarize_subject?group=1,3,5&subject=brasil%20no%20mundo&depth=10&key=aaaBBBcccDDD

Parâmetros de entrada: group: (int,int...) código do grupo. Pode ser utilizada uma lista de grupos, separados por vírgulas document: (int,int...) código do documento. Pode ser utilizada uma lista com vírgulas subject: (string) tema para o resumo depth: (int) número máximo de frases no resumo. Pode não ser encontrado um número suficiente de frases relevantes para o assunto do documento, para completar este número. A determinação do assunto é automática. key: (string) chave de autorização

<omneek_summary> <generated_results> <generated_result> <document_id> (1) <phrase_id> (2) <generated_phrase_text> (3) </generated_result> </generated_results> <original_results> <original_result> <document_id> (4) <phrase_id> (5) <oroginal_phrase_text> (6) </original_result> </original_results> </omneek_summary> (1) - código do documento da frase (2) - código da frase dentro do documento (3) - texto da frase, depois de submetido ao

algoritmo de compressão (4) - código do documento da frase (5) - código da frase dentro do documento (6) - texto original da frase

41

xml.extract_tags Descrição Extrai as palavras mais importantes num documento, ou num conjunto de frases dentro de um documento. Indicado para criar uma nuvem de tags automática, permitindo variações com plurais e não excluindo variações por gênero. Este comando permite também limitar as frases de onde vão ser retiradas as frases. Em conjunto com o comando “xml.metrics” é possível extrair a assunto de um parágrafo ou seção.

Método: xml.extract_tags

Exemplo: http://localhost/xml.extract_tags?document=5&depth=10&add_plurals=1&from_phrase_id=25&to_phrase_id=90&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento. Apenas é permitido um documento neste comando filename: (string) pode ser utilizado em vez do parâmetro “document”. Não funciona para arquivos não previamente indexados. depth: (int) número máximo de tags pretendidas from_phrase_id: (int) frase onde deve iniciar a extração de tags. Se nenhum for definida, começará no início do documento. to_phrase_id: (int) frase onde deve terminar a extração de tags. Se nenhum for definida, terminará no final do documento. use_title: (1/0) Utilizar, ou não, o título como parte importante para gerar tags key: (string) chave de autorização

<omneek_tags> <total_tags> (1) <extracted_tags> <tag> <tag_text> (2) </tag> </extracted_tags> </omneek_tags> (1) - número total de tags extraídas. Pode ser

inferior ao número definido em “depth” (2) - texto da tag. Pode ser uma palavra composta

(ex: jogo de futebol)

42

xml.tag_cloud Descrição Cria uma nuvem de tags para um texto, sem a necessidade deste ser indexado primeiro. O texto pode ser passado como parâmetro.

Método: xml.tag_cloud

Parâmetros de entrada: process_text max_tags direct_only (0/1) key: (string) chave de autorização

<omneek_tags> <total_tags> (1) <extracted_tags> <tag> <tag_text> (2) </tag> </extracted_tags> </omneek_tags> (1) - número total de tags extraídas. Pode ser

inferior ao número definido em “depth” (2) - texto da tag. Pode ser uma palavra composta

(ex: jogo de futebol)

43

xml.extract_tag_connected_entities Descrição Extrai as entidades mais importantes ligadas a uma tag. Este comando só pode ser aplicado a um documento por vez.

Método: xml.extract_tags

Exemplo: http://localhost/xml.extract_tag_connected_entities?document=5&depth=10&seed=brasil&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento. Apenas é permitido um documento neste comando filename: (string) pode ser utilizado em vez do parâmetro “document”. Não funciona para arquivos não previamente indexados. depth: (int) número máximo de tags pretendidas seed: (string) tag origem para ser relacionada key: (string) chave de autorização

<omneek_connected_entities> <total_entities> (1) <extracted_entities> <entity> <entity_text> (2) </entity> </extracted_tags> </omneek_connected_entities> (1) - número total de entidades extraídas. Pode ser

inferior ao número definido em “depth” (2) - texto da entidade. Pode ser uma palavra

composta (ex: jogo de futebol)

44

xml.compare_docs_version Descrição Comando para emitir um relatório de comparação entre dois documentos previamente indexados.

Método: xml.compare_docs_version

Exemplo: http://localhost/xml.compare_docs_version?document1=5&document2=19&detail_section=1&detail_phrase=0&key=aaaBBBcccDDD

Parâmetros de entrada: document1: (int) código do primeiro documento. É importante que seja este o documento mais antigo. document2: (int) código do segundo documento. filename1: (string) pode ser utilizado em vez do parâmetro “document1”. Não funciona para arquivos não previamente indexados. filename2: (string) pode ser utilizado em vez do parâmetro “document2”. Não funciona para arquivos não previamente indexados. detail_section: (1/0) apresentar ou não o detalhe de diferenças num comparativo de seções detail_phrase: (1/0) apresentar ou não o detalhe de diferenças de cada frase modificada key: (string) chave de autorização

<omneek_comparison_report> <comparison_result> (1) <comparison_report> <line> <line_text> (2) </line> </comparison_report> </omneek_comparison_report> (1) - descritivo do resultado geral da comparação

(ex: mesmo documento com modificações) (2) - linha do relatório

45

xml.evaluate_text Descrição Comando para avaliar a polaridade de uma frase. O texto da frase pode ser submetido diretamente como parâmetro ou pode ser identificada pelo seu id num documento previamente indexado.

Método: xml.evaluate_text

Exemplo: http://localhost/xml.evaluate_text?phrase_text=n%C3%A3o%20gostei%20do%20que%20vi&key=aaaBBBcccDDD ou http://localhost/xml.evaluate_text?document=5&phrase_id=14&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do primeiro documento. É importante que seja este o documento mais antigo. phrase_id: (int) código da frase dentro do documento indicado phrase_text: (string) Texto para avaliar polaridade. Este parâmetro, quando utilizado, inibe a utilização do “document" ou “phrase_id" key: (string) chave de autorização

<omneek_evaluation> <evaluation_value> <evaluation_description> <evaluation_support> </omneek_evaluation> (1) - valor da avaliação (6..10 = positiva, 0..4 =

negativa, 5 = neutra)

46

xml.list_inferences Descrição Comando para listar inferências automáticas extraídas dentro de um texto. Esta funcionalidade está em fase beta de desenvolvimento, por isso alguns resultados incoerentes são esperados. Os resultados incluem palavras chave que podem ser utilizadas para encontrar novas buscas ou gerar novas frases.

Método: xml.list_inferences

Parâmetros de entrada: document: (int) código do documento. Apenas um documento pode ser utilizado por vez. query: (string) filtro para inferências. Apenas as inferências relacionadas com pelo menos uma das palavras serão mostradas. key: (string) chave de autorização

<inference> <first_phrase_id> <first_phrase_text> <second_phrase_id> <second_phrase_text> <first_entity_inference> <verbal_relation_inference> <second_entity_inference> <debug> </inference >

47

xml.questionize_document Descrição Funcionalidade em desenvolvimento.

48

xml.questionize_subject Descrição Funcionalidade em desenvolvimento.

49

xml.outline Descrição Emite um índice automático para um documento, permitindo mostrar resumos ou tags por seção opcionalmente. Para documentos muito extenso, esta operação pode ter um impacto significativo no processamento, principalmente quando a opção para resumo de seção é ativada.

Método: xml.outline

Exemplo: http://localhost/xml.outline?document=5&class=1&depth=3&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento. Apenas é permitido um documento neste comando filename: (string) pode ser utilizado em vez do parâmetro “document”. Não funciona para arquivos não previamente indexados. class: (ver Anexo F) tipo de índice a emitir (títulos, tags, resumos. Ver Anexo F. depth: (int) número máximo de tags ou frases key: (string) chave de autorização

<omneek_document_outline> <total_sections> (1) <outline> <section> <section_title> (2) <section_results> (3) </section> </outline> </omneek_document_outline> (1) - total de seções no documento (2) título da seção (3) - resultados, de acordo com o parâmetro “class”

50

xml.metrics Descrição Produz um índice automático para um documento, retornando a frase onde começa e acaba cada seção. Este comando deve ser utilizado em conjunto com outros que necessitem de frase inicial e frase final.

Método: xml.metrics

Exemplo: http://localhost/xml.metrics?document=5&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento. Apenas é permitido um documento neste comando filename: (string) pode ser utilizado em vez do parâmetro “document”. Não funciona para arquivos não previamente indexados. key: (string) chave de autorização

<omneek_document_metrics> <total_sections> (1) <metrics> <metric> <metric_title> (2) <metric_initial_phrase_id> (3) <metric_final_phrase_id> (4) <metric_total_phrases> (5) </metric> </metrics> </omneek_document_metrics> (1) - total de seções no documento (2) - título da seção (3) - código da frase inicial (4) - código da frase final (5) - número total de frases no conteúdo desta

seção

51

xml.check_user Descrição Verifica se a senha para um usuário está correta.

Método: xml.check_user

Exemplo: http://localhost/xml.check_user?username=teste&password=teste&key=aaaBBBcccDDD

Parâmetros de entrada: username: (string) nome do usuário a verificar password: (string) senha para verificar key: (string) chave de autorização

<omneek> <result> (1) </omneek> (1) - resultado

52

xml.create_user Descrição Comando que permite a um supervisor, criar uma nova conta de usuário.

Método: xml.create_user

Exemplo: http://localhost/xml.create_user?supervisor_username=sup1&supervisor_password=xxx&username=teste&password=teste&email=user@omneek.com&is_supervisor=0&key=aaaBBBcccDDD

Parâmetros de entrada: supervisor_username: (string) nome do supervisor que autoriza a nova conta supervisor_password: (string) senha do supervisor que autoriza a nova conta username: (string) nome do novo usuário password: (string) senha para o novo usuário email: (string) endereço de email do novo usuário is_supervisor: (1/0) define se o novo usuário também é supervisor ou não key: (string) chave de autorização

<omneek> <result> (1) </omneek> (1) - resultado

53

xml.list_users Descrição Mostra a lista de usuários existentes no sistema. Apenas os supervisores podem visualizar a lista supervisores.

Método: xml.list_users

Exemplo: http://localhost/xml.list_users?username=teste&password=teste&key=aaaBBBcccDDD

Parâmetros de entrada: username: (string) nome do usuário que pretende ver a lista password: (string) senha do usuário que quer ver a lista key: (string) chave de autorização

<users> <user> <username> (1) <email> (2) <supervisor> (3) </user> </users> (1) - nome do usuário (2) - endereço de email (3) valor 1 se for supervisor

54

xml.change_password Descrição Comando que permite a um usuário alterar a sua própria senha.

Método: xml.change_password

Exemplo: http://localhost/xml.change_password?username=teste&old_password=teste&new_password=nova%senha&key=aaaBBBcccDDD

Parâmetros de entrada: username: (string) nome do usuário que pretende alterar a senha old_password: (string) senha atual do usuário new_password: (string) nova senha para o usuário key: (string) chave de autorização

<omneek> <result> (1) </omneek> (1) - resultado

55

xml.delete_user Descrição Comando para apagar uma conta de usuário. Apenas um supervisor pode executar este comando.

Método: xml.delete_user

Exemplo: http://localhost/xml.delete_user?supervisor_username=teste&supervisor_password=teste&delete_username=teste2&key=aaaBBBcccDDD

Parâmetros de entrada: supervisor_username: (string) nome do supervisor responsável por apagar a conta do usuário supervisor_password: (string) senha do supervisor responsável delete_username: (string) nome do usuário a apagar key: (string) chave de autorização

<omneek> <result> (1) </omneek> (1) - resultado

56

xml.no_answers Descrição Comando para consultar as pesquisas realizadas no sistema nos últimos X dias e que ficaram sem resposta. O motivo de ficarem sem resposta pode ser por não ser atingido um score mínimo, ou por não ter nada minimamente relacionado na base de conhecimento.

Método: xml.no_answers

Exemplo: http://localhost/xml.no_answers?days_before=30&group_id=3&key=aaaBBBcccDDD

Parâmetros de entrada: days_before: (int) número de dias anteriores à data atual, para incluir no relatório group_id: (int) parâmetro opcional para restringir o relatório a um grupo de documentos key: (string) chave de autorização

<queries> <query> <query_text> (1) </query> </queries> (1) - texto da pesquisa que ficou sem resposta

57

xml.stats Descrição Comando para consultar as pesquisas realizadas no sistema nos últimos X dias. Este relatório pode ser complementado com os comandos “xml.queries_for_word” e “xml.queries_for_token”.

Método: xml.stats

Exemplo: http://localhost/xml.stats?days_before=30&group_id=3&key=aaaBBBcccDDD

Parâmetros de entrada: days_before: (int) número de dias anteriores à data atual, para incluir no relatório group_id: (int) parâmetro opcional para restringir o relatório a um grupo de documentos max_results: (int) número máximo de resultados key: (string) chave de autorização

<stats> <stat> <dictionary_id> (1) <word_text> (2) <count> (3) </stat> </stats> (1) - código da palavra, para ser utilizado com

“xml.query_for_token” (2) - texto da palavra, para ser utilizado com

“xml.query_for_word” (3) - número de ocorrências em pesquisas

58

xml.queries_for_word Descrição Permite consultar as pesquisas completas onde foi utilizada a palavra especificada.

Método: xml.queries_for_word

Exemplo: http://localhost/xml.queries_for_word?days_before=30&group_id=3&word_text=pesquisar&key=aaaBBBcccDDD

Parâmetros de entrada: days_before: (int) número de dias anteriores à data atual, para incluir no relatório group_id: (int) parâmetro opcional para restringir o relatório a um grupo de documentos word_text: (string) palavra pretendida key: (string) chave de autorização

<stats> <stat> <query> (1) </stat> </stats> (1) - frase da pesquisa

59

xml.queries_for_token Descrição Permite consultar as pesquisas completas onde foi utilizada a palavra especificada através do seu código no léxico.

Método: xml.queries_for_token

Exemplo: http://localhost/xml.queries_for_token?days_before=30&group_id=3&token_id=3000123&key=aaaBBBcccDDD

Parâmetros de entrada: days_before: (int) número de dias anteriores à data atual, para incluir no relatório group_id: (int) parâmetro opcional para restringir o relatório a um grupo de documentos token_id: (int) código no léxico da palavra pretendida. Este código vem do comando “xml.stats” key: (string) chave de autorização

<stats> <stat> <query> (1) </stat> </stats> (1) - frase da pesquisa

60

xml.flush_stats Descrição Limpa as estatísticas existentes, anteriores ao número de dias especificado.

Método: xml.flush_stats

Exemplo: http://localhost/xml.flush_stats?days_before=30&group_id=3&key=aaaBBBcccDDD

Parâmetros de entrada: days_before: (int) número de dias anteriores à data atual, para incluir no relatório group_id: (int) parâmetro opcional para restringir o relatório a um grupo de documentos key: (string) chave de autorização

<omneek> <result> (1) </omneek> (1) - resultado

61

xml.increment_rank_score Descrição Este comando permite aumentar a popularidade de um documento. Pode ser executado sempre que um documento é aberto. A popularidade aumenta o score de um documento nas pesquisas através do “xml.search_best_doc” em até 2 pontos.

Método: xml.increment_rank_score

Exemplo: http://localhost/xml.increment_rank_score?document=21&key=aaaBBBcccDDD

Parâmetros de entrada: document: (int) código do documento key: (string) chave de autorização

<omneek> <result> (1) </omneek> (1) - resultado

62

Anexo A Lista de tipos de ordenação

Tipo Descrição

0 Ordenação por data de indexação, decrescente

1 Ordenação por ordem alfabética de título

2 Ordenação por ordem alfabética de título, decrescente

3 Ordenação por data de indexação

40 Ordenação por rank score decrescente e data de indexação descrescente

41 Ordenação por rank score decrescente e ordem alfabética de título

42 Ordenação por rank score decrescente e ordem alfabética de título descrescente

43 Ordenação por rank score decrescente e data de indexação

63

Anexo B Lista de perfis de busca

Tipo Descrição

0 Busca semântica, incluindo a valorização de palavras indiretas, sinônimos, abstrações verbais, plurais, gênero e outras

1 Busca direta, excluído associações entre palavras, mas incluindo abstrações de gênero, plural e outras

2 Busca semântica abreviada

3 Busca que valoriza mais as ligações entre palavras, mesmo sendo mais remotas. Ex: “calor” pontua o mesmo que “sol”, quando a pesquisa é feita por “sol”)

4 Busca semântica eficiente, pontua apenas relações diretas

5 Busca para respostas. Indicada quando o usuário coloca as pesquisa em forma de pergunta.

6 Busca detalhada. Perfil mais lento de busca, que irá retornar mais resultados do que o normal, incluindo alguns remotamente relacionados.

64

Anexo C Critérios para “nested search”

Tipo Descrição

1 Apenas retorna resultados que tenham resultados em ambas as buscas

2 Retorna todos os resultados que venham de qualquer uma das buscas.

65

Anexo D Tipo de texto complementar para “xml.ask”

Tipo Descrição

0 Frase relevante para resposta

1 Título do documento + frase relevante

2 Título do documento + texto da seção onde foi encontrada a frase relevante

3 Título do documento + texto do parágrafo onde foi encontrada a frase relevante

4 Texto completo da seção onde foi encontrada a frase relevante

5 Título da seção onde foi encontrada a frase + frase relevante

6 Título da seção onde foi encontrada a frase + texto completo da seção onde foi encontrada a frase

7 Título da seção onde foi encontrada a frase + texto do parágrafo onde foi encontrada a frase

8 Texto do parágrafo onde foi encontrada a frase relevante

9 Texto completo do documento

10 Título do documento

11 Título da seção onde foi encontrada a frase relevante

66

Anexo E Tipo de resultados para “xml.outline”

Tipo Descrição

0 Título + tags da seção

1 Título + texto condensado da seção

67

Anexo F Estrutura de arquivos complementares do OmneeK Learner

Extensão Descrição

.SCI Este arquivo acompanha um arquivo de conteúdo (ver Anexo H para lista de completa de tipos arquivos de conteúdo). Ele permite indicar ao OmneeK Learner alguns dados de armazenamento e classificação. Tags permitidas: origin_filename: public_filename: group_name: content_type: find_evaluations: store_declarative_knowledge: datetime: total_comments: delete_from_knowledge_origin_filename:

.SNI Arquivo gerado pelo OmneeK Spider, para aprender arquivos em batch Tags permitidas: delete_from_knowledge_origin_filename: change_origin_filename: [...] delete_from_knowledge_origin_filename: change_origin_filename:

.DOIT Arquivo para executar um comando de duração elevada, como apagar ou mover documentos ou grupos. Os arquivos DOIT são independentes de arquivos de conteúdo. Tags permitidas: delete_document_id:doc_id (int);override_family_id (int) move_document_id:document_id;family_id (int) move_group_id:group_id1;group_id2 (int) delete_group_id:group_id (int) delete_all: (1/0); (1/0)(teached_meanings, teached_evaluations)

.RESP Arquivo que acompanha um arquivo de conteúdo e que permite que seja enviada uma resposta por email, quando a indexação deste arquivo for concluída. O arquivo pode conter um ou mais endereços de email (sem tag inicial). Um por linha.

.SPIRESP Avisar por email que um batch de arquivos foi indexado.

.FAMI Permite especificar o nome do grupo onde o arquivo deve ser guardado.