Databricks SDK pour Go

Dans cet article, vous apprendrez à automatiser les opérations Databricks et à accélérer le développement avec le SDK Databricks pour Go. Cet article complète le SDK Databricks pour Go README, la référence de l'API et les exemples.

remarque

Cette fonctionnalité est en Beta et peut être utilisée en production.

Pendant la période bêta, Databricks vous recommande de pin une dépendance sur la version mineure spécifique du SDK Databricks pour Go dont votre code dépend, par exemple, dans le fichier go.mod d'un projet. Pour plus d'informations sur l'épinglage des dépendances, consultez Gestion des dépendances.

Exigences

Pour utiliser le SDK Databricks pour Go, votre machine de développement doit disposer de :

• Go installé.
• Databricks authentication configured.

Démarrer avec le Databricks SDK pour Go

1. Sur votre machine de développement avec Go déjà installé, un projet de code Go existant déjà créé et l'authentification Databricks configurée, créez un fichier go.mod pour suivre les dépendances de votre code Go en exécutant la commande go mod init, par exemple :

   Bash

   go mod init sample

2. Prenez une dépendance vis-à-vis du package Databricks SDK for Go en exécutant la commande go mod edit -require, en remplaçant 0.8.0 par la dernière version du package Databricks SDK for Go, telle qu'indiquée dans le CHANGELOG:

   Bash

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

   Votre fichier go.mod devrait maintenant ressembler à ceci :

   Go

   module sample
   
   go 1.18
   
   require github.com/databricks/databricks-sdk-go v0.8.0

3. Dans votre projet, créez un fichier de code Go qui importe le Databricks SDK pour Go. L'exemple suivant, dans un fichier nommé main.go avec le contenu suivant, répertorie tous les clusters de votre workspace Databricks :

   Go

   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. Ajoutez toutes les dépendances de module manquantes en exécutant la commande go mod tidy :

   Bash

   go mod tidy

remarque

Si vous obtenez l'erreur go: warning: "all" matched no packages, vous avez oublié d'ajouter un fichier de code Go qui importe le SDK Databricks pour Go.

5. Récupérez des copies de tous les packages nécessaires pour prendre en charge les builds et les tests des packages dans votre module main, en exécutant la commande go mod vendor :

   Bash

   go mod vendor

6. Configurez votre machine de développement pour l'authentification Databricks.

7. Exécutez votre fichier de code Go, en supposant un fichier nommé main.go, en exécutant la commande go run :

   Bash

   go run main.go

remarque

En ne définissant pas *databricks.Config comme argument dans l'appel précédent à w := databricks.Must(databricks.NewWorkspaceClient()), le SDK Databricks pour Go utilise son processus par default pour tenter d'effectuer l'authentification Databricks. Pour remplacer ce comportement par default, consultez Authentifier le SDK Databricks pour Go avec votre compte Databricks ou votre Workspace.

Mettre à jour le SDK Databricks pour Go

Pour mettre à jour votre projet Go afin d'utiliser l'un des packages du SDK Databricks pour Go, tel qu'indiqué dans le CHANGELOG, procédez comme suit :

1. Exécutez la commande go get depuis la racine de votre projet, en spécifiant l'indicateur -u pour effectuer une mise à jour, et en fournissant le nom et le numéro de version cible du package Databricks SDK pour Go. Par exemple, pour mettre à jour vers la version 0.12.0, exécutez la commande suivante :

   Bash

   go get -u github.com/databricks/databricks-sdk-go@v0.12.0

2. Ajoutez et mettez à jour toutes les dépendances de module manquantes et obsolètes en exécutant la commande go mod tidy :

   Go

   go mod tidy

3. Obtenez des copies de tous les nouveaux packages et packages mis à jour nécessaires pour prendre en charge les builds et les tests de packages dans votre module main, en exécutant la commande go mod vendor :

   Go

   go mod vendor

Authentifier le SDK Databricks pour Go avec votre compte ou workspace Databricks

Le SDK Databricks pour Go implémente le standard d'authentification unifiée Databricks , une approche architecturale et programmatique consolidée et cohérente de l'authentification. Cette approche contribue à rendre la configuration et l'automatisation de l'authentification avec Databricks plus centralisées et prévisibles. Il vous permet de configurer l'authentification Databricks une seule fois, puis d'utiliser cette configuration sur plusieurs outils Databricks et SDK sans modifications supplémentaires de la configuration de l'authentification. Pour plus d'informations, y compris des exemples de code plus complets en Go, consultez Authentification unifiée Databricks.

Voici quelques-uns des modèles de codage disponibles pour initialiser l'authentification Databricks avec le SDK Databricks pour Go :

• Utilisez l'authentification par default de Databricks en procédant comme suit :

  • Créez ou identifiez un profil de configuration Databricks personnalisé avec les champs requis pour le type d'authentification Databricks cible. Définissez ensuite la variable d'environnement DATABRICKS_CONFIG_PROFILE sur le nom du profil de configuration personnalisé.
  • Définissez les variables d'environnement requises pour le type d'authentification Databricks cible.

  Instanciez ensuite par exemple un objet WorkspaceClient avec l'authentification default de Databricks comme suit :

  Go

  import (
    "github.com/databricks/databricks-sdk-go"
  )
  // ...
  w := databricks.Must(databricks.NewWorkspaceClient())

• Le codage en dur des champs obligatoires est pris en charge mais non recommandé, car il risque d'exposer des informations sensibles dans votre code, tels que les jetons d'accès personnel Databricks. L'exemple suivant code en dur les valeurs d'hôte Databricks et de jeton d'accès pour l'authentification par jeton Databricks :

  Go

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

Voir aussi l'authentification dans le README du Databricks SDK pour Go.

Exemples

Les exemples de code suivants montrent comment utiliser le Databricks SDK pour Go afin de créer et de supprimer des clusters, d'exécuter des jobs et de répertorier les utilisateurs du compte. Ces exemples de code utilisent le processus d'authentification par default de Databricks SDK pour Go.

Pour des exemples de code supplémentaires, consultez le dossier examples du repository Databricks SDK for Go dans GitHub.

• Créer un cluster
• Supprimer définitivement un cluster
• Exécuter un job
• Gérer les fichiers dans les volumes Unity Catalog
• Lister les utilisateurs du compte

Créer un cluster

Cet exemple de code crée un cluster avec la dernière version disponible de Databricks Runtime Long Term Support (LTS) et le plus petit type de nœud de cluster disponible avec un disque local. Ce cluster dispose d'un Worker, et le cluster sera automatiquement arrêté après 15 minutes d'inactivité. L'appel de méthode CreateAndWait met le code en pause jusqu'à ce que le nouveau cluster soit en cours d'exécution dans l'Workspace.

Go

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
}

Supprimer définitivement un cluster

Cet exemple de code supprime définitivement le cluster avec l'ID de cluster spécifié du Workspace.

Go

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)
  }
}

Exécuter un job

Cet exemple de code crée un Job Databricks qui exécute le notebook spécifié sur le cluster spécifié. Lorsque le code s’exécute, il récupère le chemin d’accès du notebook existant, l’ID du cluster existant et les paramètres de job associés auprès de l’utilisateur au terminal. L’appel de méthode RunNowAndWait met le code en pause jusqu’à ce que le nouveau job ait terminé son exécution dans le workspace.

Go

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)
}

Gérer les fichiers dans les volumes Unity Catalog

Cet exemple de code montre divers appels à la fonctionnalité files dans WorkspaceClient pour accéder à un volume Unity Catalog.

Go

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,
    },
  )
}

Liste des utilisateurs du compte

Cet exemple de code liste les utilisateurs disponibles au sein d'un compte Databricks.

Go

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)
  }
}

Dépannage

Cette section décrit des solutions aux problèmes courants avec le SDK Databricks pour Go.

Pour signaler des problèmes ou tout autre commentaire, créez une demande GitHub pour le SDK Databricks pour Go.

Erreur : impossible d'analyser la réponse

Si vous recevez l’erreur suivante lorsque vous tentez d’utiliser le Databricks SDK pour Go, cela indique presque toujours un problème avec votre configuration d’authentification.

Error: unable to parse response. This is likely a bug in the Databricks SDK for Go or the underlying REST API.

Si vous rencontrez cette erreur, vérifiez ce qui suit :

• Assurez-vous que votre hôte Databricks est correctement configuré.
• Confirmez que la méthode d’authentification dispose des autorisations requises pour l’opération d’API que vous tentez d’effectuer.
• Si vous êtes derrière un pare-feu d'entreprise, assurez-vous qu'il ne bloque ni ne redirige le trafic API.

Une cause fréquente de cette erreur est le Link privé qui redirige le SDK vers une page de connexion, que le SDK ne peut pas traiter. Cela se produit généralement en essayant d'accéder à un Workspace compatible Link privé, configuré sans accès Internet public, à partir d'un réseau différent de celui auquel appartient l'Endpoint Virtual Private Cloud (VPC).

Pour plus de détails, consultez :

• Authentification unifiée Databricks

Ressources supplémentaires

Pour plus d'informations, voir :

• Databricks SDK for Go README
• Databricks SDK pour Go référence de l'API
• Exemples de code supplémentaires
• Journalisation
• Test en cours
• Opérations de longue durée
• Réponses paginées