Criar e compartilhar snippets

Nesta página

Criar um pacote de snippet

Publicar um snippet
Instale o novo pacote de snippet
Contribuir com um pacote de snippet para a MongoDB Community

Aviso

Recurso experimental

Esse recurso é experimental. O MongoDB não é compatível com snippets. Este recurso pode ser alterado ou removido a qualquer momento sem aviso prévio.

Bugs não são esperados, no entanto, se você encontrar um, abra um problema no Github repositório do para este projeto.

Você pode escrever scripts para manipular dados ou realizar tarefas administrativas no mongosh. Empacotar um script como um snippet oferece uma maneira de compartilhar facilmente scripts dentro da sua organização ou na comunidade de usuários do MongoDB .

Esta página discute:

Preparação de um pacote de snippet.
Publicação do pacote de snippet em um registro.

Para obter exemplos de scripts e arquivos de metadados em pacote de snippet, consulte os snippets no registro de snippet da comunidade no Github.

Dica

Se você planeja enviar seu snippet para o registro da comunidade, certifique-se de revisar as informações em Contribuir com um pacote de snippet para a MongoDB Community.

Criar um pacote de snippet

As etapas desta seção focam em empacotar um roteiro. Para obter mais detalhes sobre como escrever roteiros, consulte Escrever roteiros.

Preparar os arquivos

Fazer um fork do repositório da comunidade.

Se você planeja contribuir para o repositório da comunidade, faça um fork do repositório do projeto de snippets.

Você não precisa bifurcar o repositório da comunidade se quiser criar um repositório privado, mas deve recriar manualmente uma estrutura de diretório semelhante à medida que trabalha nas etapas a seguir.

Crie um diretório de pacotes.

Crie um diretório para seu pacote de trecho no diretório snippets no repositório com fork. Este diretório conterá o código do seu roteiro e vários arquivos de metadados.

Este exemplo mostra diretórios para dois pacotes de snippet, decrypt-cards e update-auth. O conteúdo dos diretórios dos snippets de comunidade são omitidos para maior clareza.

mongo-snippets
|
├── scripts
│   ├── make-index.js
│   └── show-index.js
└── snippets
    ├── analyze-schema
    ├── decrypt-cards
    │   ├── LICENSE-Community.txt
    │   ├── README.md
    │   ├── error-matchers.js
    │   ├── index.js
    │   └── package.json
    ├── mock-collection
    ├── mongocompat
    ├── resumetoken
    ├── spawn-mongod
    └── update-auth
        ├── LICENSE
        ├── README.md
        ├── index.js
        └── package.json

Crie `README.md`.

Crie um README.md. O README.md descreve como usar seu código. Este arquivo é exibido quando um usuário insere snippet help para seu snippet.

Crie `LICENSE`.

Crie um arquivo LICENSE . Você precisará inserir uma string de identificador de licença mais tarde, portanto, tente escolher uma licença na lista de licenças do SPDX.

Crie `index.js`.

Crie um arquivo index.js.

Esse arquivo contém o ponto de entrada do seu código que é exposto no console mongosh.
O roteiro é escrito em JavaScript e define suas novas funções.
O roteiro pode estar em um único arquivo ou em vários arquivos.
O roteiro pode chamar outros arquivos e módulos npm locais ou remotos. Para require() um módulo npm remoto, use a construção:
```
const localRequire = require('module').createRequire(__filename);)
```
Para ver um exemplo, consulte index.js no snippet resumetoken.
index.js é referenciado em package.json.
O repositório MongoDB tem código de exemplo.

Dica

Se você tiver um roteiro existente, renomeie-o index.js ou crie um arquivo index.js para carregá-lo. Para obter um exemplo de um arquivoindex.js que carrega outros roteiros, confira este no repositório da comunidade.

Preparar o `package.json` arquivo

package.json contém metadados que o registro do pacote utiliza para gerenciar snippets.

Um arquivo package.json mínimo tem a seguinte aparência:

{
    "name": "@mongosh/snippet-resumetoken",
    "snippetName": "resumetoken",
    "version": "1.0.2",
    "description": "Resume token decoder script",
    "main": "index.js",
    "license": "Apache-2.0",
    "publishConfig": {
       "access": "public"
    }
}

Os parâmetros são:

Campo	Descrição
"nome"	O pacote npm que contém o snippet.
"snippetName"	O nome do trecho. Este é o nome usado com comandos como `install`.
"versão"	A versão do pacote. Isso deve ser incrementado quando você atualizar seu snippet.
"description"	Uma breve observação sobre o que seu snippet faz. Atenção: se a descrição tiver mais de 50 ou 60 caracteres, ela poderá causar problemas de exibição com alguns comandos de snippet.
"main"	Este é o ponto de partida do seu código, `index.js`. Observe que as funções em outros arquivos podem ser definidas para que também estejam disponíveis no shell `mongosh`.
"license"	A licença para usuários do seu código. Se você deseja contribuir para o registro compartilhado, a licença deve ser da lista de licenças SPDX . Consulte também o Contrato de Colaborador do MongoDB.
"publishConfig"	Este valor é usado para controlar o acesso ao seu pacote de snippet. `public` é o mais comum, mas o npm oferece outras opções também.

Use este código para criar um arquivo package.json de base. Edite o arquivo e substitua cada UPDATE para inserir os valores do seu pacote de snippet.

{
    "name": "@UPDATE/UPDATE",
    "snippetName": "UPDATE",
    "version": "UPDATE",
    "description": "UPDATE",
    "main": "UPDATE",
    "license": "UPDATE",
    "publishConfig": {
       "access": "UPDATE"
    }
}

Existem vários exemplos de package.json arquivos no MongoDB Github repositório .

Dica

O MongoDB usa npm como registro de pacote.

o npm depende do arquivo package.json para gerenciar pacotes. Consulte a documentação do pacote npm para mais informações sobre package.json.

Publicar um snippet

Para compartilhar seu snippet, você deve publicar seu pacote de snippet em um registro. O pacote conterá:

Seu código
README.md
LICENSE file
package.json

Quando os arquivos estiverem concluídos, siga estas etapas para criar e publicar seu pacote de snippet.

Crie um arquivo de índice de registro.

O arquivo de índice do registro não é o mesmo que o arquivo index.js que contém seu código de snippet. O arquivo de índice de registro, index.bson.br, contém metadados para os pacotes de snippet em seu registro.

O arquivo de índice de registro deve ser compactado antes de ser carregado para uso. O create-index.js O utilitário no diretório de scripts percorre seus diretórios de origem de trecho coletando as informações necessárias para criar o arquivo de índice de registro. Depois de criar o arquivo de índice do registro, o script make-index.js também o compacta.

Execute create-index.js a partir do mongo-snippets diretório crie o índice.

node ./scripts/make-index.js

A saída deste script é um arquivo compactado arquivo de índice de registro, index.bson.br.

Você pode usar show-index.js para exibir o arquivo de índice de registro compactado.

Usar make-index.js é a melhor maneira de criar um índice de registro, mas também é possível criar um índice de registro manualmente.

Confirme seu snippet

Confirme seu trecho e o arquivo de índice de registro em seu repositório do Github .

Publicar alterações

Publique suas alterações no registro npm.

npm publish --access public

Instale o novo pacote de snippet

Siga estas etapas para instalar seu novo pacote de snippet:

Atualizar metadados.

Atualize os metadados do snippet em seu mongosh local.

snippet refresh

Instale o snippet.

snippet install YOUR_NEW_SNIPPET

Contribuir com um pacote de snippet para a MongoDB Community

Se você escreveu um snippet de código que pode ser útil para outros usuários do MongoDB, convidamos você a colocá-lo no repositório da comunidade hospedada no Github.

Para enviar um trecho para o repositório compartilhado do MongoDB :

Conclua o Contrato de Colaborador.

Leia e preencha o Contrato de Colaborador do MongoDB.

Clone o repositório.

Faça um fork e clone o repositório do projeto de snippet do Github.

Crie seu diretório de pacotes.

Adicione um novo diretório para seu código em snippets/. Dê a ele um nome descritivo.

Crie seu pacote.

Crie seu pacote de snippet. Confirme se ele contém os seguintes arquivos:

package.json
index.js
README.md
LICENSE

Você não precisa criar um arquivo de índice de registro. Se seu pacote de snippet for aceito, o MongoDB atualizará o arquivo de índice do registro.

Confirme suas alterações.

Confirme suas alterações no repositório do Github .

Envie seu código de snippet.

Abra uma solicitação pull no repositório do projeto snippet.

O MongoDB analisará sua solicitação pull. Se for aceito, nós:

Mesclaremos seu código em nosso repositório Github.
Publicar no registro npm.
Adicionaremos ao índice do snippet.

Voltar

Uso no Console

Registros

Aviso

Recurso experimental

Dica

Criar um pacote de snippet

Preparar os arquivos

Fazer um fork do repositório da comunidade.

Crie um diretório de pacotes.

Crie README.md.

Crie LICENSE.

Crie index.js.

Dica

Preparar o package.json arquivo

Dica

Publicar um snippet

Crie um arquivo de índice de registro.

Confirme seu snippet

Publicar alterações

Instale o novo pacote de snippet

Atualizar metadados.

Instale o snippet.

Contribuir com um pacote de snippet para a MongoDB Community

Conclua o Contrato de Colaborador.

Clone o repositório.

Crie seu diretório de pacotes.

Crie seu pacote.

Confirme suas alterações.

Envie seu código de snippet.

Crie `README.md`.

Crie `LICENSE`.

Crie `index.js`.

Preparar o `package.json` arquivo