---
url: https://docs.ogmabox.com/pt/plugins/backend-sdk.md
description: >-
  Referência das APIs de plugins de backend do Ogma, execução em sandbox,
  caminhos de armazenamento, acesso ao histórico HTTP, achados, comandos e
  integração com o aplicativo principal.
---

# Referência do SDK de backend para plugins {#plugin-backend-sdk-reference}

O código dos plugins de backend é executado no sandbox de JavaScript do Ogma e recebe um objeto `sdk` do aplicativo principal.

Para conhecer o formato completo do pacote de plugin, os campos do manifesto, as permissões e os exemplos, comece pelo [guia do sistema de plugins](./README.md).

## Ponto de entrada {#entry-point}

Os plugins de backend expõem uma função `init`:

```js
async function init(sdk) {
  sdk.console.log("plugin started");
}
```

O Ogma chama `init(sdk)` quando o plugin é habilitado.

## Namespaces principais {#core-namespaces}

| Namespace | Finalidade |
| --- | --- |
| `sdk.console` | Gravar mensagens no buffer de logs do plugin. |
| `sdk.meta` | Ler os metadados e os caminhos de dados do plugin. |
| `sdk.events` | Registrar callbacks para eventos do Ogma. |
| `sdk.requests` | Consultar o histórico HTTP e os dados das requisições. |
| `sdk.findings` | Consultar ou criar achados quando as permissões permitem. |
| `sdk.scope` | Ler informações do escopo ativo. |
| `sdk.storage` | Persistência de chave/valor para o estado do plugin. |
| `sdk.fs` | Operações de arquivos no diretório privado de dados do plugin. |
| `sdk.path` | Funções auxiliares para compor caminhos no diretório de dados do plugin. |
| `sdk.api` | Expor handlers do backend ao frontend do plugin. |

## Logs {#logging}

```js
sdk.console.log("message")
sdk.console.warn("warning")
sdk.console.error("error")
```

As mensagens aparecem na interface de logs do plugin. Mantenha os logs concisos e evite gravar segredos.

## Metadados {#metadata}

```js
sdk.meta.id()
sdk.meta.packageId()
sdk.meta.version()
sdk.meta.path()
```

Use `sdk.meta.path()` para dados específicos do plugin. Não presuma que o código do plugin executado em sandbox pode acessar caminhos arbitrários do sistema de arquivos.

```js
sdk.storage.set("key", "value")
sdk.storage.get("key")
sdk.storage.keys()
sdk.storage.delete("key")
sdk.storage.clear()
```

```js
sdk.fs.readFile("relative/file.txt")
sdk.fs.writeFile("relative/file.txt", "text")
sdk.fs.appendFile("relative/file.txt", "more")
sdk.fs.exists("relative/file.txt")
sdk.fs.existsSync("relative/file.txt")
sdk.fs.mkdir("relative/dir")
sdk.path.join("a", "b", "c")
```

## Eventos {#events}

```js
sdk.events.onInterceptRequest(function(req) {
  return req
})

sdk.events.onInterceptResponse(function(req, res) {
  sdk.console.log(res.getCode())
})

sdk.events.onProjectChange(function() {
  sdk.console.log("project changed")
})
```

Os callbacks devem ser rápidos. Tarefas demoradas devem ser executadas mediante ações explícitas do usuário ou handlers da API do backend.

## Handlers da ponte com o frontend {#frontend-bridge-handlers}

Os plugins de backend podem expor handlers para os painéis de frontend dos plugins:

```js
sdk.api.register("ping", async function(input) {
  return { ok: true, input: input };
});
```

O frontend chama o handler pelo SDK de frontend do Ogma. Consulte a [referência do SDK de frontend](./frontend-sdk.md).

## Requisitos de segurança {#security-expectations}

* Trate o tráfego HTTP, os achados, os logs e as exportações como dados sensíveis.
* Solicite somente as permissões de que seu plugin precisa.
* Nunca registre credenciais, cookies, tokens de portador ou tráfego privado por padrão.
* Mantenha o comportamento do plugin explícito e compreensível para o usuário.