Criar, atualizar, e apagar KS via API

Os exemplos nesta seção usam curl e shell scripts. Você pode adaptá-los para outras linguagens com a StackSpot AI.

Pré-Requisitos

• Você precisa se autenticar para usar os scripts;
  • Para contas Freemium: configurar o seu Personal Access Token (PAT).
  • Para contas Enterprise: escolha entre usar as Credenciais de Serviço ou PAT.

  Siga os passos para autenticar na página de Credenciais de Serviço, para mais detalhes, acesse a documentação da StackSpot EDP.

Entre em contato com o administrador da sua conta se não conseguir criar uma Credencial de Serviço.

• Ative as permissões ai_dev e ai_admin para conseguir criar credenciais;

Dicas!

• Copie os e salve os campos 'client id', 'client key', e 'realm' para usar como variáveis de ambiente (os dois primeiros devem ser segredos) ou no exemplo curl na parte inferior da página na seção 'como usar'. Você não poderá vê-los novamente.

Se você perder alguma delas, revogue a credencial e crie uma nova.

• Depois de gerar o seu token (PAT ou Credencial de Serviço), você pode reutilizá-lo sempre que precisar executar integrações via API na StackSpot AI. Não é necessário criar um novo token a cada uso.

• Os exemplos a seguir consideram que o token de acesso está definido como a variável de ambiente JWT. Você pode extrair isso da autenticação curl com o comando jq para obter o valor para a chave access_token do JSON retornado, depois salvá-lo como uma variável de ambiente usando o comando export, como:

export JWT=$(curl -s "https://idm.stackspot.com/$REALM/oidc/oauth/token" -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_KEY" | jq -r '.access_token')

Criar um Knowledge Source via API

Siga os passos:

Passo 1. Execute este comando para criar um novo Knowledge Source (KS):

curl -s -X POST "https://data-integration-api.stackspot.com/v1/knowledge-sources" -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"slug": "my-cli-ks-v2", "name": "my-cli-ks-v2", "description": "KS created via CLI using form v2", "type": "<one of api, snippet or custom>"}'

Passo 2. No Portal da StackSpot AI,vá até a seção ‘Knowledge Sources’ e confira se o KS foi criado;

Enviar arquivos (upload) para um Knowledge Source existente

Atenção!

O tamanho máximo por arquivo é 10 MB.

Cuidado!

Importância da extensão do arquivo

Ao fazer upload de arquivos para um Knowledge Source, a extensão no campo file_name é essencial. A StackSpot AI utiliza a extensão do arquivo para identificar corretamente a sintaxe do conteúdo, garantindo que o material enviado seja processado e categorizado de forma adequada.

Por que a extensão do arquivo é importante

A extensão do arquivo permite que a StackSpot AI:

1. Identifique automaticamente a sintaxe do conteúdo do arquivo;
2. Aplique as regras de análise corretas para um processamento preciso;
3. Torne o conteúdo fácil para pesquisar e utilizável dentro do Knowledge Source.

Exemplo

Se você fazer o upload de um arquivo chamado example.json, a StackSpot AI processará como um arquivo JSON. Se a extensão estiver ausente ou incorreta, o sistema pode não interpretar o conteúdo corretamente.

Quais extensões são permitidas?

Essa lista é variável confirme o tipo de Knowledge Source.

• API: json e yaml.
• Custom: txt, md, json, yaml e pdf.
• Snippet: abap, ada, adb, ads, aes, cls, azcli, bat, cmd, bicep, c, h, cs, cpp, cc, cxx, hh, hpp, hxx, mligo, prg, clj, cljs, cljc, edn, cob, cbl, coffee, csp, css, d, dart, dockerfile, ecl, ex, exs, erl, hrl, fs, fsi, ml, mli, flow, f90, f, for, f77, ftl, go, graphql, gql, groovy, gvy, gy, gsh, handlebars, hbs, hs, hcl, tf, html, htm, ini, java, js, mjs, jsx, json, jl, kt, kts, less, lex, liquid, lua, m3, md, dax, asm, sql, m, pas, pp, ligo, pl, pm, php, pla, txt, dats, sats, hats, pq, ps1, psm1, psd1, proto, pug, py, qs, r, rkt, cshtml, redis, rego, rst, rb, rs, sb, lisp, scala, scm, scss, sh, sol, rq, st, swift, sv, tcl, twig, ts, tsx, vb, v, xml, yaml, yml.

ZIP é aceito, mas só arquivos suportados serão processados. Você pode fazer o upload de um ou mais arquivos para um Knowledge Source existente. Também é possível escolher fazer o upload de um arquivo zip.

Siga os passos a seguir para fazer o upload de arquivos para um Knowledge Source existente:

Atenção!

Antes de continuar, verifique se você já criou o seu Knowledge Source.
Se ainda não criou, saiba como criar um Knowledge Source.

Passo 1. Execute o seguinte script para iniciar o processo de upload, enviando o arquivo para a StackSpot AI:

Você precisa substituir todos os campos do exemplo (placeholders) pelos valores corretos do seu ambiente.

upload_data=$(curl -X POST 'https://data-integration-api.stackspot.com/v2/file-upload/form' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d '{"file_name": "<desired file's name>", "target_id": "<KS slug>", "target_type": "KNOWLEDGE_SOURCE", "expiration": 600 }')

echo -n 'file upload id = '
echo "$upload_data" | jq -r '.id'

curl -X POST "$(echo "$upload_data" | jq -r '.url')" \
  -F "key=$(echo "$upload_data" | jq -r '.form.key')" \
  -F "x-amz-algorithm=$(echo "$upload_data" | jq -r '.form["x-amz-algorithm"]')" \
  -F "x-amz-credential=$(echo "$upload_data" | jq -r '.form["x-amz-credential"]')" \
  -F "x-amz-date=$(echo "$upload_data" | jq -r '.form["x-amz-date"]')" \
  -F "x-amz-security-token=$(echo "$upload_data" | jq -r '.form["x-amz-security-token"]')" \
  -F "policy=$(echo "$upload_data" | jq -r '.form.policy')" \
  -F "x-amz-signature=$(echo "$upload_data" | jq -r '.form["x-amz-signature"]')" \
  -F 'file=@"<absolute path to desired file>"'

Passo 2. Execute o comando a seguir para iniciar a conversão do arquivo enviado em objetos no Knowledge Source:

curl -X POST "https://data-integration-api.stackspot.com/v1/file-upload/$(echo "$upload_data" | jq -r '.id')/knowledge-objects" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $JWT" \
-d '{ "split_strategy": "<one of NONE, LINES_QUANTITY, TOKENS_QUANTITY, CHARACTERS_QUANTITY, SYNTACTIC>", "split_quantity": 500, "split_overlap": 50 }'

Dica!

Use o método para dividir os Knowledge Objects (KOs) (Split Strategy) conforme o tipo de Knowledge Source:

• API: NONE, ENDPOINT.
• SNIPPET: NONE, LINES_QUANTITY, TOKENS_QUANTITY, SYNTACTIC.
• CUSTOM: NONE, LINES_QUANTITY, TOKENS_QUANTITY, CHARACTERS_QUANTITY, SYNTACTIC.

Para visualizar o processo de divisão e entender melhor esses parâmetros, vá até o Portal da StackSpot AI e tente adicionar o arquivo ao seu Knowledge Source.

Passo 3. Para verificar o status do upload, execute o comando:

curl --location "https://data-integration-api.stackspot.com/v1/file-upload/$(echo "$upload_data" | jq -r '.id')" --header "Authorization: Bearer $JWT"

Exemplo de resposta:

{
  "id": "ULID",
  "file_name": "string",
  "target_id": "string",
  "target_type": "KNOWLEDGE_SOURCE",
  "status": "NEW | PROCESSING | SPLITTED | INDEXED | SPLIT_ERROR | ERROR",
  "error_description": "string",
  "summary": {
    "added": "int",
    "preserved": "int",
    "removed": "int",
    "errors": {"string": "string"}
  }
}

Passo 4. Acesse o Portal da StackSpot AI

Passo 5. Clique em ‘Knowledge Sources’ e depois verifique se o seu Knowledge Source possui novos objetos.

Se você receber um erro 403, você não tem permissão para acessar o Knowledge Source.

Listar todos os Knowledge Objects (KO)

Você pode listar todos os Knowledge Objects para recuperar os conteúdos dele. Para isso, execute:

curl -s -X GET "https://data-integration-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects" -H "Authorization: Bearer $JWT"

Como apagar Knowledge Objects

Apagar Knowledge Object por ID

Se você deseja apagar um Knowledge Object por ID, execute no seu terminal:

curl -X 'DELETE' 'https://data-integration-api.stackspot.com/v1/knowledge-sources/<ks slug>/objects/<ko id>' -H "Authorization: Bearer $JWT"

Apagar todos os arquivos

Se você deseja apagar todos os Knowledge Source Objects, execute no seu terminal:

curl -s -X DELETE "https://data-integration-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects" -H "Authorization: Bearer $JWT"

Apagar apenas os objetos Standalone (manualmente)

Se você deseja excluir apenas o arquivo independente que você adicionou manualmente:

curl -s -X DELETE "https://data-integration-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects?standalone=true" -H "Authorization: Bearer $JWT"

Apagar apenas uploads (ZIP, arquivos enviados)

Para excluir os arquivos zip, execute o seguinte:

curl -s -X DELETE "https://data-integration-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects?standalone=false" -H "Authorization: Bearer $JWT"