Partilhar via


SDK do Databricks para Go

Neste artigo, você aprenderá a automatizar operações em contas, espaços de trabalho e recursos relacionados do Azure Databricks com o SDK do Databricks for Go. Este artigo complementa o Databricks SDK for Go README, referência de API e exemplos.

Nota

Este recurso está em Beta e pode ser usado na produção.

Durante o período Beta, o Databricks recomenda que você fixe uma dependência na versão secundária específica do SDK do Databricks for Go da qual seu código depende, por exemplo, no arquivo de go.mod um projeto. Para obter mais informações sobre como fixar dependências, consulte Gerenciando dependências.

Antes de começar

Antes de começar a usar o Databricks SDK for Go, sua máquina de desenvolvimento deve ter:

Introdução ao SDK do Databricks para Go

  1. Em sua máquina de desenvolvimento com o Go já instalado, um projeto de código Go existente já criado e a autenticação do Azure Databricks configurada, crie um go.mod arquivo para controlar as dependências do código Go executando o go mod init comando, por exemplo:

    go mod init sample
    
  2. Pegue uma dependência do pacote Databricks SDK for Go executando o go mod edit -require comando, substituindo 0.8.0 pela versão mais recente do pacote Databricks SDK for Go, conforme listado no CHANGELOG:

    go mod edit -require github.com/databricks/databricks-sdk-go@v0.8.0
    

    O seu go.mod ficheiro deve agora ter o seguinte aspeto:

    module sample
    
    go 1.18
    
    require github.com/databricks/databricks-sdk-go v0.8.0
    
  3. Dentro do seu projeto, crie um arquivo de código Go que importe o SDK do Databricks para Go. O exemplo a seguir, em um arquivo nomeado main.go com o seguinte conteúdo, lista todos os clusters em seu espaço de trabalho do Azure Databricks:

    package main
    
    import (
      "context"
    
      "github.com/databricks/databricks-sdk-go"
      "github.com/databricks/databricks-sdk-go/service/compute"
    )
    
    func main() {
      w := databricks.Must(databricks.NewWorkspaceClient())
      all, err := w.Clusters.ListAll(context.Background(), compute.ListClustersRequest{})
      if err != nil {
        panic(err)
      }
      for _, c := range all {
        println(c.ClusterName)
      }
    }
    
  4. Adicione quaisquer dependências de módulo ausentes executando o go mod tidy comando:

    go mod tidy
    

    Nota

    Se você receber o erro go: warning: "all" matched no packages, esqueceu de adicionar um arquivo de código Go que importa o Databricks SDK for Go.

  5. Pegue cópias de todos os pacotes necessários para suportar compilações e testes de pacotes em seu main módulo, executando o go mod vendor comando:

    go mod vendor
    
  6. Configure sua máquina de desenvolvimento para autenticação do Azure Databricks.

  7. Execute seu arquivo de código Go, assumindo um arquivo chamado main.go, executando o go run comando:

    go run main.go
    

    Nota

    Ao não definir *databricks.Config como um argumento na chamada anterior para w := databricks.Must(databricks.NewWorkspaceClient()), o SDK do Databricks para Go usa seu processo padrão para tentar executar a autenticação do Azure Databricks. Para substituir esse comportamento padrão, consulte Autenticar o SDK do Databricks para Go com sua conta ou espaço de trabalho do Azure Databricks.

Atualizar o SDK do Databricks para Go

Para atualizar seu projeto Go para usar um dos pacotes Databricks SDK for Go, conforme listado no CHANGELOG, faça o seguinte:

  1. Execute o go get comando a partir da raiz do seu projeto, especificando o -u sinalizador para fazer uma atualização e fornecendo o nome e o número da versão de destino do pacote Databricks SDK for Go. Por exemplo, para atualizar para a versão 0.12.0, execute o seguinte comando:

    go get -u github.com/databricks/databricks-sdk-go@v0.12.0
    
  2. Adicione e atualize quaisquer dependências de módulo ausentes e desatualizadas executando o go mod tidy comando:

    go mod tidy
    
  3. Pegue cópias de todos os pacotes novos e atualizados necessários para suportar compilações e testes de pacotes em seu main módulo, executando o go mod vendor comando:

    go mod vendor
    

Autenticar o SDK do Databricks para Go com sua conta ou espaço de trabalho do Azure Databricks

O Databricks SDK for Go implementa o padrão de autenticação unificada do cliente Databricks, uma abordagem arquitetônica e programática consolidada e consistente para autenticação. Essa abordagem ajuda a tornar a configuração e a automação da autenticação com o Azure Databricks mais centralizadas e previsíveis. Ele permite que você configure a autenticação do Databricks uma vez e, em seguida, use essa configuração em várias ferramentas e SDKs do Databricks sem mais alterações na configuração de autenticação. Para obter mais informações, incluindo exemplos de código mais completos em Go, consulte Autenticação unificada do cliente Databricks.

Alguns dos padrões de codificação disponíveis para inicializar a autenticação Databricks com o Databricks SDK for Go incluem:

  • Use a autenticação padrão do Databricks seguindo um destes procedimentos:

    • Crie ou identifique um perfil de configuração personalizado do Databricks com os campos necessários para o tipo de autenticação Databricks de destino. Em seguida, defina a DATABRICKS_CONFIG_PROFILE variável de ambiente como o nome do perfil de configuração personalizado.
    • Defina as variáveis de ambiente necessárias para o tipo de autenticação Databricks de destino.

    Em seguida, instancie, por exemplo, um WorkspaceClient objeto com a autenticação padrão do Databricks da seguinte maneira:

    import (
      "github.com/databricks/databricks-sdk-go"
    )
    // ...
    w := databricks.Must(databricks.NewWorkspaceClient())
    
  • A codificação rígida dos campos obrigatórios é suportada, mas não recomendada, pois corre o risco de expor informações confidenciais em seu código, como tokens de acesso pessoal do Azure Databricks. O exemplo a seguir codifica valores de token de host e acesso do Azure Databricks para autenticação de token Databricks:

    import (
      "github.com/databricks/databricks-sdk-go"
      "github.com/databricks/databricks-sdk-go/config"
    )
    // ...
    w := databricks.Must(databricks.NewWorkspaceClient(&databricks.Config{
      Host:  "https://...",
      Token: "...",
    }))
    

Consulte também Autenticação no Databricks SDK for Go README.

Exemplos

Os exemplos de código a seguir demonstram como usar o Databricks SDK for Go para criar e excluir clusters, executar trabalhos e listar usuários de conta. Estes exemplos de código usam o processo de autenticação padrão do Azure Databricks SDK for Go do Databricks.

Para obter exemplos de código adicionais, consulte a pasta de exemplos no repositório Databricks SDK for Go no GitHub.

Criar um cluster

Este exemplo de código cria um cluster com a versão mais recente disponível do Databricks Runtime Long Term Support (LTS) e o menor tipo de nó de cluster disponível com um disco local. Esse cluster tem um trabalhador e o cluster será encerrado automaticamente após 15 minutos de tempo ocioso. A CreateAndWait chamada de método faz com que o código pause até que o novo cluster esteja em execução no espaço de trabalho.

package main

import (
  "context"
  "fmt"

  "github.com/databricks/databricks-sdk-go"
  "github.com/databricks/databricks-sdk-go/service/compute"
)

func main() {
  const clusterName            = "my-cluster"
  const autoTerminationMinutes = 15
  const numWorkers             = 1

  w   := databricks.Must(databricks.NewWorkspaceClient())
  ctx := context.Background()

  // Get the full list of available Spark versions to choose from.
  sparkVersions, err := w.Clusters.SparkVersions(ctx)

  if err != nil {
    panic(err)
  }

  // Choose the latest Long Term Support (LTS) version.
  latestLTS, err := sparkVersions.Select(compute.SparkVersionRequest{
    Latest:          true,
    LongTermSupport: true,
  })

  if err != nil {
    panic(err)
  }

  // Get the list of available cluster node types to choose from.
  nodeTypes, err := w.Clusters.ListNodeTypes(ctx)

  if err != nil {
    panic(err)
  }

  // Choose the smallest available cluster node type.
  smallestWithLocalDisk, err := nodeTypes.Smallest(clusters.NodeTypeRequest{
    LocalDisk: true,
  })

  if err != nil {
    panic(err)
  }

  fmt.Println("Now attempting to create the cluster, please wait...")

  runningCluster, err := w.Clusters.CreateAndWait(ctx, compute.CreateCluster{
    ClusterName:            clusterName,
    SparkVersion:           latestLTS,
    NodeTypeId:             smallestWithLocalDisk,
    AutoterminationMinutes: autoTerminationMinutes,
    NumWorkers:             numWorkers,
  })

  if err != nil {
    panic(err)
  }

  switch runningCluster.State {
  case compute.StateRunning:
    fmt.Printf("The cluster is now ready at %s#setting/clusters/%s/configuration\n",
      w.Config.Host,
      runningCluster.ClusterId,
    )
  default:
    fmt.Printf("Cluster is not running or failed to create. %s", runningCluster.StateMessage)
  }

  // Output:
  //
  // Now attempting to create the cluster, please wait...
  // The cluster is now ready at <workspace-host>#setting/clusters/<cluster-id>/configuration
}

Excluir permanentemente um cluster

Este exemplo de código exclui permanentemente o cluster com a ID de cluster especificada do espaço de trabalho.

package main

import (
  "context"

  "github.com/databricks/databricks-sdk-go"
  "github.com/databricks/databricks-sdk-go/service/clusters"
)

func main() {
  // Replace with your cluster's ID.
  const clusterId = "1234-567890-ab123cd4"

  w   := databricks.Must(databricks.NewWorkspaceClient())
  ctx := context.Background()

  err := w.Clusters.PermanentDelete(ctx, compute.PermanentDeleteCluster{
    ClusterId: clusterId,
  })

  if err != nil {
    panic(err)
  }
}

Executar uma tarefa

Este exemplo de código cria um trabalho do Azure Databricks que executa o bloco de anotações especificado no cluster especificado. À medida que o código é executado, ele obtém o caminho do bloco de anotações existente, o ID do cluster existente e as configurações de trabalho relacionadas do usuário no terminal. A RunNowAndWait chamada de método faz com que o código pause até que o novo trabalho termine de ser executado no espaço de trabalho.

package main

import (
  "bufio"
  "context"
  "fmt"
  "os"
  "strings"

  "github.com/databricks/databricks-sdk-go"
  "github.com/databricks/databricks-sdk-go/service/jobs"
)

func main() {
  w   := databricks.Must(databricks.NewWorkspaceClient())
  ctx := context.Background()

  nt := jobs.NotebookTask{
    NotebookPath: askFor("Workspace path of the notebook to run:"),
  }

  jobToRun, err := w.Jobs.Create(ctx, jobs.CreateJob{
    Name: askFor("Some short name for the job:"),
    Tasks: []jobs.JobTaskSettings{
      {
        Description:       askFor("Some short description for the job:"),
        TaskKey:           askFor("Some key to apply to the job's tasks:"),
        ExistingClusterId: askFor("ID of the existing cluster in the workspace to run the job on:"),
        NotebookTask:      &nt,
      },
    },
  })

  if err != nil {
    panic(err)
  }

  fmt.Printf("Now attempting to run the job at %s/#job/%d, please wait...\n",
    w.Config.Host,
    jobToRun.JobId,
  )

  runningJob, err := w.Jobs.RunNow(ctx, jobs.RunNow{
    JobId: jobToRun.JobId,
  })

  if err != nil {
    panic(err)
  }

  jobRun, err := runningJob.Get()

  if err != nil {
    panic(err)
  }

  fmt.Printf("View the job run results at %s/#job/%d/run/%d\n",
    w.Config.Host,
    jobRun.JobId,
    jobRun.RunId,
  )

  // Output:
  //
  // Now attempting to run the job at <workspace-host>/#job/<job-id>, please wait...
  // View the job run results at <workspace-host>/#job/<job-id>/run/<run-id>
}

// Get job settings from the user.
func askFor(prompt string) string {
  var s string
  r := bufio.NewReader(os.Stdin)
  for {
    fmt.Fprint(os.Stdout, prompt+" ")
    s, _ = r.ReadString('\n')
    if s != "" {
      break
    }
  }
  return strings.TrimSpace(s)
}

Gerenciar arquivos em volumes do Catálogo Unity

Este exemplo de código demonstra várias chamadas para files funcionalidade dentro WorkspaceClient para acessar um volume do Catálogo Unity.

package main

import (
  "context"
  "io"
  "os"

  "github.com/databricks/databricks-sdk-go"
  "github.com/databricks/databricks-sdk-go/service/files"
)

func main() {
  w := databricks.Must(databricks.NewWorkspaceClient())

  catalog          := "main"
  schema           := "default"
  volume           := "my-volume"
  volumePath       := "/Volumes/" + catalog + "/" + schema + "/" + volume // /Volumes/main/default/my-volume
  volumeFolder     := "my-folder"
  volumeFolderPath := volumePath + "/" + volumeFolder // /Volumes/main/default/my-volume/my-folder
  volumeFile       := "data.csv"
  volumeFilePath   := volumeFolderPath + "/" + volumeFile // /Volumes/main/default/my-volume/my-folder/data.csv
  uploadFilePath   := "./data.csv"

  // Create an empty folder in a volume.
  err := w.Files.CreateDirectory(
    context.Background(),
    files.CreateDirectoryRequest{DirectoryPath: volumeFolderPath},
  )
  if err != nil {
    panic(err)
  }

  // Upload a file to a volume.
  fileUpload, err := os.Open(uploadFilePath)
  if err != nil {
    panic(err)
  }
  defer fileUpload.Close()

  w.Files.Upload(
    context.Background(),
    files.UploadRequest{
      Contents:  fileUpload,
      FilePath:  volumeFilePath,
      Overwrite: true,
    },
  )

  // List the contents of a volume.
  items := w.Files.ListDirectoryContents(
    context.Background(),
    files.ListDirectoryContentsRequest{DirectoryPath: volumePath},
  )

  for {
    if items.HasNext(context.Background()) {
      item, err := items.Next(context.Background())
      if err != nil {
        break
      }
      println(item.Path)

    } else {
      break
    }
  }

  // List the contents of a folder in a volume.
  itemsFolder := w.Files.ListDirectoryContents(
    context.Background(),
    files.ListDirectoryContentsRequest{DirectoryPath: volumeFolderPath},
  )

  for {
    if itemsFolder.HasNext(context.Background()) {
      item, err := itemsFolder.Next(context.Background())
      if err != nil {
        break
      }
      println(item.Path)
    } else {
      break
    }
  }

  // Print the contents of a file in a volume.
  file, err := w.Files.DownloadByFilePath(
    context.Background(),
    volumeFilePath,
  )
  if err != nil {
    panic(err)
  }

  bufDownload := make([]byte, file.ContentLength)

  for {
    file, err := file.Contents.Read(bufDownload)
    if err != nil && err != io.EOF {
      panic(err)
    }
    if file == 0 {
      break
    }

    println(string(bufDownload[:file]))
  }

  // Delete a file from a volume.
  w.Files.DeleteByFilePath(
    context.Background(),
    volumeFilePath,
  )

  // Delete a folder from a volume.
  w.Files.DeleteDirectory(
    context.Background(),
    files.DeleteDirectoryRequest{
      DirectoryPath: volumeFolderPath,
    },
  )
}

Listar usuários da conta

Este exemplo de código lista os usuários disponíveis em uma conta do Azure Databricks.

package main

import (
  "context"

  "github.com/databricks/databricks-sdk-go"
  "github.com/databricks/databricks-sdk-go/service/iam"
)

func main() {
  a := databricks.Must(databricks.NewAccountClient())
  all, err := a.Users.ListAll(context.Background(), iam.ListAccountUsersRequest{})
  if err != nil {
    panic(err)
  }
  for _, u := range all {
    println(u.UserName)
  }
}

Recursos adicionais

Para obter mais informações, consulte: