11 Blocos de Notas
Este capítulo fornece informações sobre como usar e gerenciar notebooks em seu espaço de trabalho.
Desenvolver Código em Notebooks
Engenheiros e cientistas de dados podem usar notebooks em seu Workbench da Oracle AI Data Platform como uma ferramenta comum para desenvolver código e explorar dados interativamente.
O Workbench da Oracle AI Data Platform atualmente suporta linguagens Python, SQL e Scala em notebooks. Notebooks podem ser programados ou configurados para serem executados como parte de um workflow. Para executar notebooks, você precisa anexar um cluster de computação.
Seu Workbench da Plataforma de Dados de IA vem com notebooks gerenciados integrados para uma experiência intuitiva do desenvolvedor.
Você pode usar o código de amostra no repositório Git Amostras do Oracle AI Data Platform Workbench para obter exemplos de código que você pode usar com seu notebook.
Salvar automaticamente
Notebooks são salvos automaticamente a cada dois minutos.
Importando e Exportando Notebooks
No momento, você pode importar um arquivo de notebook (*.ipynb) da sua máquina local para o seu espaço de trabalho.
A exportação de notebooks não é suportada no momento.
Criar um Bloco de Notas
Você pode criar um notebook em qualquer espaço de trabalho que tenha permissões de administrador.
- Na Home page, navegue até seu espaço de trabalho.
- Clique em Criar e em Livro de Notas.
- Preencha o nome da descrição e, em seguida, clique em Criar.
Anexar um Cluster Existente a um Notebook
Os notebooks exigem um cluster anexado para fornecer capacidade de computação para o código desenvolvido.
Criar um Cluster para um Notebook
Você pode criar um novo cluster diretamente na interface de notebook e anexá-lo imediatamente.
- Na Home page, navegue até o espaço de trabalho e abra o notebook.
- Clique em Ações e, em seguida, clique em Criar cluster.
- Selecione Versão de runtime.
- Selecione as opções de driver para o cluster.
- Selecione as opções de colaborador para seu cluster. Essas opções se aplicam a todos os colaboradores do cluster.
- Selecione se o número de colaboradores é estático ou se é dimensionado automaticamente.
- Se Valor estático, especifique o número de colaboradores.
- Se Dimensionamento Automático, especifique o número mínimo e máximo de colaboradores para os quais o cluster pode ser dimensionado.
- Para Duração da execução, selecione se o cluster será interrompido após uma duração definida de inatividade. Se Timeout de inatividade for selecionado, especifique o tempo de inatividade, em minutos, antes do timeout do cluster.
- Clique em Criar.
Idioma Padrão
Você pode usar notebooks para desenvolver e executar o código Apache Spark em Python, SQL ou Scala.
A linguagem padrão para notebooks é Python. Você pode alterar o idioma padrão de todo o notebook ou de células individuais para SQL, Scala, Markdown ou texto bruto. Você pode combinar código Python, SQL e Scala em células diferentes dentro do mesmo notebook.
Notebooks têm realce de sintaxe para Python, SQL e Scala. Novas células de notebook serão criadas com base no idioma padrão do notebook.
Gerenciar Notebooks
Você pode renomear e excluir seus próprios notebooks. Você também pode clonar notebooks para copiar seu conteúdo e trabalhar com seu código em um novo notebook.
Renomeie e exclua seus notebooks do menu de ação deles no seu espaço de trabalho. Você clona seu notebook abrindo-o e selecionando a opção Clonar no menu Arquivo.
Renomear um Notebook
Se o nome do seu notebook não for mais útil ou relevante, você poderá alterá-lo a qualquer momento.
- Na Home page, navegue até seu espaço de trabalho.
- Ao lado do notebook que você deseja renomear, clique em Ações e depois em Renomear.
- Informe um novo nome, e clique em Salvar.
- Opcional: Você também pode alterar o nome de um notebook aberto clicando no nome e informando um novo.
Excluir um Notebook
Você pode excluir notebooks para os quais tem permissões de administrador.
- Navegue até o seu espaço de trabalho.
- Ao lado do notebook que você deseja excluir, clique em Ações e, em seguida, em Excluir.
- Clique em Excluir.
Clonar um Notebook
Você pode clonar um notebook existente para criar uma cópia do conteúdo desse notebook que pode modificar enquanto mantém o original.
- Abra o bloco de anotações que deseja clonar.
- Na barra de ferramentas do notebook, clique em Arquivo e, em seguida, clique em Clonar.
- Informe um novo nome para o caderno clonado.
- Clique em Procurar para selecionar a pasta do espaço de trabalho na qual salvar o notebook clonado. Se nenhuma pasta for selecionada, o notebook clonado será criado na mesma pasta que o notebook que você está clonando.
- Selecione se deseja incluir ou excluir saídas. As saídas são incluídas por padrão. Desmarque a seleção para excluir saídas.
- Clique em Clonar. O notebook clonado é criado na pasta do espaço de trabalho especificada.
Procurar Recursos ao Editar Notebook
Quando estiver em um notebook, você poderá procurar os objetos do Catálogo ou do espaço de trabalho no lado esquerdo sem sair do notebook.
Se você arrastar e soltar qualquer objeto do painel esquerdo para o notebook, o nome do objeto ou o caminho completo será copiado e colado na célula do notebook (dependendo do contexto).
Você também tem um botão e opções de menu de contexto disponíveis para cada objeto de catálogo ou espaço de trabalho no painel esquerdo. O menu de contexto na navegação esquerda tem opções para copiar o código de amostra, o nome da cópia ou o caminho da cópia e, assim, você pode colar na célula do notebook.
Executar Notebooks
Você pode executar código em notebooks que possui ou em notebooks que são compartilhados com você.
O código pode ser executado de um notebook usando três métodos: executar sob demanda, executar como uma execução manual única ou criar um job de notebook programado. Os trabalhos executados sob demanda são executados apenas uma vez.
Executando Comandos de Terminal em um Notebook
Você pode executar comandos básicos de terminal ou comandos de shell dentro de um notebook prefixando com um '!'. Por exemplo, você pode usar o comando unzip para extrair dos arquivos ZIP no espaço de trabalho.
Você também pode usar o módulo subprocess no Python para execução de script shell.
Você também pode usar módulos Python nativos como zipfile para tarefas como descompactar arquivos como uma alternativa aos comandos shell.
Limitações
Atualmente, o Oracle AI Data Platform Workbench não tem suporte nativo para sistemas de instalação de pip, CI/CD, Git ou controle de versão.
Opções de Execução para Células de Notebook
O menu Run em notebooks fornece opções para executar células em um notebook.
<Insira o Título da Seção Aqui>
Você pode encontrar todas as opções para executar células no seu notebook no menu Executar na parte superior do seu notebook.
Tabela 11-1 Opções de Execução para Células de Notebook
| Opção | Descrição |
|---|---|
| Executar tudo | Executa todas as células no notebook sequencialmente. |
| Executar célula(s) selecionada(s) | Executa as células selecionadas no momento. |
| Executar tudo acima | Executa a célula selecionada no momento e as células que aparecem acima da célula selecionada no notebook. |
| Executar tudo abaixo | Executa a célula selecionada no momento e as células que aparecem abaixo da célula selecionada no notebook. |
| Executar texto selecionado | Executa o segmento de código selecionado em uma célula. |
| Ir para célula da última execução | Navega até a célula executada mais recentemente no notebook. |
| Limpar todas as saídas de célula | Remove saídas de todas as células do notebook. |
Executar Código de um Notebook
Você pode optar por executar todo o código desenvolvido em um notebook de uma só vez ou uma célula de cada vez.
- MacOS: Cmd + Return
- Windows: Ctrl + Enter
Você pode executar o código em uma única célula clicando no botão 
Reproduzir ou executar todo o notebook clicando em Executar tudo.
- Na Home page, clique em Espaço de Trabalho.
- Navegue até o seu notebook.
- Clique em Executar tudo.
- Verifique o status da execução do job de notebook clicando em Workflow e depois em Execuções de Jobs.
Executar Código de Outro Notebook
Você pode usar o comando %run magic em um notebook para incluir código de outro notebook.
Após seguir essas etapas, o notebook chamado called-notebook.ipynb é executado imediatamente usando o seu controlador de usuários (ou seja, caller-notebook.ipynb) e usando o cluster anexado de caller-notebook.ipynb. Todas as funções e variáveis definidas em chamado-notebook.ipynb ficam imediatamente disponíveis no notebook chamado caller-notebook.ipynb.
Compartilhar Saída de Notebook com oidlUtils
Você pode capturar e compartilhar a saída de conteúdo por suas tarefas de notebook usando utilitários disponíveis no oidlUtils.
oidlUtils é um conjunto de utilitários disponíveis para todos os usuários do Oracle AI Data Platform Workbench. Ao compartilhar conteúdo entre notebooks, oidlUtils pode ser chamado para transmitir argumentos a um notebook e transmitir a saída de volta ao notebook do chamador, e pode ser chamado em uma tarefa de job em um notebook para transmitir a saída de volta à tarefa pai, ou seja, a tarefa que chama o notebook. Usado dessa forma, você pode capturar e usar a saída estruturada retornada por suas tarefas de notebook.
Estes módulos oidlUtils estão disponíveis para uso com notebooks:
| Módulo | Descrição | Exemplo |
|---|---|---|
| caderno | Orquestre execuções de tarefas de notebook e retorne um único resultado estruturado (geralmente uma string JSON) ao chamador. | |
| caderno | Permita que um notebook saia de uma execução de tarefa e retorne um único resultado de string (geralmente um payload JSON) para a API de saída de notebook ou job/tarefa do chamador. | |
Exemplo 1: Compartilhamento de Notebook para Notebook
Neste exemplo, você usa o Notebook A para chamar o Notebook B. O Notebook B retorna um payload de resultado que o Notebook A está configurado para capturar e usar.
Caderno A
result = oidlUtils.notebook.run("NotebookB", 0)
print("Output from Notebook B:", result)
import json
payload = {
"status": "SUCCESS",
"rows_processed": 1234,
"output_table": "sales_gold",
"run_id": "run_2026_02_11"
}
json_payload = json.dumps(payload)
oidlUtils.notebook.exit(str(json_payload))
Saída do Notebook B
{"status": "SUCCESS", "rows_processed": 1234, "output_table": "sales_gold", "run_id": "run_2026_02_11"}Exemplo 2: Passando a Saída pelas Tarefas de Cargo
Neste exemplo, você retorna um arquivo JSON quando seu notebook é executado como uma tarefa: oidlUtils.notebook.exit(json.dumps(payload)).
import json
payload = {
"status": "SUCCESS",
"output_table": "sales_gold",
"rows_processed": 1234
}
oidlUtils.notebook.exit(json.dumps(payload))
Em seguida, você executa o job com sua tarefa de notebook e obtém a saída da tarefa por meio da chamada de API: endpoint = f"https://<workspace-url>/jobs/runs/get-output?run_id={task_run_id}" and response = requests.get(endpoint, headers=headers).json().
import requests
task_run_id = "<task_run_id>"
endpoint = f"https://<workspace-url>/jobs/runs/get-output?run_id={task_run_id}"
response = requests.get(endpoint, headers=headers).json()
Por último, você captura a saída retornada pelo notebook com job_result = response['notebook_output']['result'].
job_result = response["notebook_output"]["result"]
payload = json.loads(job_result)
print(payload["output_table"]) # Output : sales_gold
print(payload["rows_processed"]) # Output : 1234
Navegação de Notebook
Você pode criar e manter um índice que pode ser usado para organizar e navegar em seu notebook.
Você pode clicar no ícone do sumário no canto superior esquerdo do notebook para exibir uma estrutura de tópicos do notebook. O sumário é gerado automaticamente com base nos cabeçalhos de markdown que você pode criar, permitindo fácil organização e navegação.
Você pode adicionar texto formatado, cabeçalhos, listas e documentação como markdown para organizar e explicar o conteúdo do notebook para você e outros usuários.
Criar uma Célula de Markdown
Você pode criar células de markdown para fornecer cabeçalhos no sumário do seu notebook para facilitar a organização e a navegação.
- Na Home page, navegue até o notebook.
- Na lista suspensa de tipo de célula, selecione Markdown.
- Adicione seu markdown à célula.
- As células de markdown podem incluir texto formatado, cabeçalhos, listas e outras documentações.
- Para criar um cabeçalho, inicie uma linha com # seguida de um espaço. O cabeçalho 1 usa um #, o cabeçalho 2 usa ##. Adicione # adicional para cada nível de cabeçalho adicional.
Saída e Resultados do Notebook
Você pode ver saídas de notebook e resultados em uma nova célula que aparece logo após a célula com código.
Enquanto uma célula estiver em andamento, você poderá cancelar a execução da célula. Se um notebook for executado como um job de workflow, a saída não ficará visível no mesmo notebook. Nesse caso, a saída fica visível na área de saída da execução do job de workflow correspondente.
Você pode fazer download da saída da célula de saída como um arquivo CSV ou Excel. Você também pode copiar o conteúdo da célula de saída diretamente para a área de transferência.
Fazer Download da Saída do Notebook
Você pode fazer download da saída resultante de uma célula de notebook diretamente do painel de resultados.
- No canto superior direito da célula da qual você deseja fazer download da saída, clique em Fazer Download.
- No menu, selecione o formato do qual deseja fazer download da saída.
Copiar Saída do Notebook
Você pode copiar a saída resultante de uma célula de notebook diretamente do painel de resultados.
- No canto superior direito da célula da qual você deseja fazer download da saída, clique em Copiar.
- O conteúdo da célula de saída é copiado diretamente para a área de transferência. Você pode colá-lo em outro lugar no seu notebook ou em um local externo.
Aparência do Notebook
Você pode alterar o espaço de tela disponível para trabalhar em notebooks minimizando o painel de navegação esquerdo ou expandindo a exibição de notebook.
Você pode minimizar o painel de navegação esquerdo do Oracle AI Data Platform Workbench enquanto trabalha no seu notebook para aumentar o espaço de tela utilizável clicando em Minimizar painel na parte inferior direita do painel de navegação.
Você também pode expandir o notebook clicando em Expandir no canto superior direito do notebook, expandindo o espaço disponível e facilitando a leitura de células e saídas maiores.
Números de Execução da Célula
Cada célula de notebook exibe um número de execução que indica a ordem na qual as células foram executadas. Esse número é atualizado toda vez que a célula é executada. Você pode executar células em qualquer ordem, de modo que os números de execução podem não corresponder à ordem física das células no seu notebook.
Gerenciar Execuções de Jobs
Você pode criar execuções de jobs para gerenciar como e quando o código é executado em seus notebooks.
As execuções manuais de job podem ser executadas novamente ou posteriormente configuradas para execução em uma programação. As execuções de job programadas são acionadas automaticamente com base na programação definida. A menos que um agendamento seja configurado, os trabalhos manuais são executados apenas uma vez.
Criar um Job de Execução Manual de um Notebook
Você pode criar um job não programado que possa ser executado manualmente com base no código que desenvolveu no seu notebook.
- Na Home page, clique em Espaço de Trabalho.
- Navegue até o seu notebook.
- Clique em Ações e em Programar.
- Forneça um nome e descrição para o job.
- Clique em Procurar e selecione o local onde armazenar seu job. Clique em Selecionar.
- Selecione um cluster de computação na lista drop-down Cluster.
- Para Programação, selecione Execução Manual.
- Clique em Criar.
Criar uma Execução de Job Programado com Base em um Notebook
Você pode criar um job programado que seja executado automaticamente com base no código que você desenvolveu no seu notebook.
- Na Home page, clique em Espaço de Trabalho.
- Navegue até o seu notebook.
- Clique em Ações e em Programar.
- Forneça um nome e descrição para o job.
- Clique em Procurar e selecione o local onde armazenar seu job. Clique em Selecionar.
- Selecione um cluster de computação na lista drop-down Cluster.
- Para Programar, selecione Programar.
- Selecione um Status da Programação.
- Selecione Ativo se quiser que a programação seja ativada imediatamente.
- Selecione Pausado se quiser ativar manualmente a execução programada posteriormente.
- Forneça um fuso horário para o agendamento ser baseado.
- Selecione o Tipo de Programação.
- Para Calendário, você deve especificar a frequência e em quais horas ou dias a programação se repetirá.
- Para Expressão Cron, você deve fornecer a programação na forma de uma expressão cron.
- Verifique o tempo de execução listado na parte inferior para confirmar se sua programação está correta. Clique em Criar.
Atalhos de teclado de notebook
Você pode usar atalhos de teclado para simplificar o uso de comandos no seu notebook.
| Windows | macOS | Ação |
|---|---|---|
| Ctrl + Enter | Cmd + Devolução | Executar célula |
| Shift + Enter | Turno + Retorno | Executar célula e avançar para a próxima célula |
| Ctrl + S | Cmd + S | Salvar caderno |
| Ctrl + N | Ctrl + N | Novo notebook |
| Ctrl + Z | Cmd + Z | Desfazer |
| Ctrl + Y | Cmd + S | Refazer |
| Ctrl + C | Cmd + C | Copiar |
| Ctrl + X | Cmd +X | Recortar |
| Ctrl + V | Cmd + V | Colar |
| Ctrl + Alt + F | Ctrl + Opção + F | Localizar e Substituir |
| Ctrl + Shift + A | Ctrl + Shift + A | Inserir células acima |
| Ctrl + Shift + B | Ctrl + Shift + B | Inserir células abaixo |
| Ctrl + Alt + Acima | Ctrl + Opção + Acima | Mover célula para cima |
| Ctrl + Alt + Down | Ctrl + Opção +Down | Mover célula para baixo |
| Ctrl + D | Ctrl + D | Excluir célula |
| Alt + Shift + Enter | Opção + Turno + Retorno | Executar Todos |
| Alt + Shift + Acima | Opção + Shift + Up | Executar todas as células acima |
Migre o Código Apache Spark Existente para o Oracle AI Data Platform Workbench
Você pode adaptar seu código do Apache Spark para migrá-lo para uso nos notebooks do Oracle AI Data Platform Workbench.
Se você estiver migrando o código Spark existente de outras plataformas, poderá usar as diretrizes a seguir para adaptar seu código para uso em notebooks.
Tabela 11-2 Diretrizes de Migração do Apache Spark para a Plataforma de Dados AI
| Diretriz | Detalhes |
|---|---|
| Remover comandos de criação do SparkSession | O AI Data Platform Workbench cria automaticamente um SparkContext para cada cluster de computação. Recomendamos remover os comandos de criação de sessão ou substituí-los por SparkSession.builder().getOrCreate().
|
Remova comandos de encerramento de sessão, como sys.exit() ou spark.stop() |
Todos os clusters de computação de finalidade são compartilhados; portanto, se algum usuário interromper a SparkSession usando sys.exit() ou spark.stop(), por exemplo, o cluster precisará ser reiniciado para todos. Para evitar interrupções, recomendamos evitar esses comandos nos notebooks.
|