Secrets API 2.0

Med API:et Hemligheter kan du hantera hemligheter, hemliga omfång och åtkomstbehörigheter. Om du vill hantera hemligheter måste du:

  1. Skapa en omfattning för en hemlighet.
  2. Lägg till dina hemligheter i omfånget.
  3. Om du har Azure Databricks Premium Plantilldelar du åtkomstkontroll till det hemliga omfånget.

Mer information om hur du skapar och hanterar hemligheter finns i Hemlighetshantering och Hemlig åtkomstkontroll. Du kommer åt och refererar till hemligheter i notebook-filer och jobb med hjälp av verktyget Hemligheter (dbutils.secrets).

Viktigt

För att få åtkomst till Databricks REST API:er måste du autentisera. Om du vill använda hemlighets-API:et med Azure Key Vault hemligheter måste du autentisera med hjälp av en Azure Active Directory token.

Skapa hemligt omfång

Slutpunkt HTTP-metod
2.0/secrets/scopes/create POST

Du kan antingen:

  • Skapa ett Azure-Key Vault-stödda omfång där hemligheter lagras i Azure-hanterad lagring och krypteras med en molnbaserad specifik krypteringsnyckel.
  • Skapa ett Databricks-säkerhetskopierat hemlighetsomfång där hemligheter lagras i Databricks-hanterad lagring och krypteras med en molnbaserad specifik krypteringsnyckel.

Skapa ett Azure Key Vault-backat omfång

Omfångsnamnet:

  • Måste vara unikt i en arbetsyta.
  • Måste bestå av alfanumeriska tecken, bindestreck, understreck och punkter och får inte överstiga 128 tecken.

Namnen anses vara icke-känsliga och kan läsas av alla användare på arbetsytan. Som standard är en arbetsyta begränsad till högst 100 hemliga omfång. Om du vill öka maxgränsen för en arbetsyta kontaktar du din Databricks-representant.

Exempel

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/secrets/scopes/create \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <token>" \
--header "X-Databricks-Azure-SP-Management-Token: <management-token>" \
--data @create-scope.json

create-scope.json:

{
  "scope": "my-simple-azure-keyvault-scope",
  "scope_backend_type": "AZURE_KEYVAULT",
  "backend_azure_keyvault":
  {
    "resource_id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azure-rg/providers/Microsoft.KeyVault/vaults/my-azure-kv",
    "dns_name": "https://my-azure-kv.vault.azure.net/"
  },
  "initial_manage_principal": "users"
}

Ersätt:

I det här exemplet används en .netrc-fil .

Om initial_manage_principal anges tillämpas den första ACL som tillämpas på omfånget på det angivna huvudkontot (användare, tjänstens huvudnamn eller grupp) med MANAGE behörigheter. Det enda huvudnamn som stöds för det här alternativet är gruppen users, som innehåller alla användare på arbetsytan. Om initial_manage_principal inte anges tilldelas den första ACL:n med MANAGE behörighet som tillämpas på omfånget till API-begärandeutfärdarens användaridentitet.

Genererar RESOURCE_ALREADY_EXISTS om det redan finns ett omfång med det angivna namnet. Utlöser RESOURCE_LIMIT_EXCEEDED om det maximala antalet omfång på arbetsytan överskrids. Utlöser INVALID_PARAMETER_VALUE om omfångsnamnet är ogiltigt.

Mer information finns i Skapa ett Azure Key Vault-säkerhetskopierat hemlighetsomfång med Databricks CLI.

Skapa en omfattning för en hemlighet som stöds av Databricks

Omfångsnamnet:

  • Måste vara unikt i en arbetsyta.
  • Måste bestå av alfanumeriska tecken, bindestreck, understreck och punkter och får inte överstiga 128 tecken.

Namnen anses vara icke-känsliga och kan läsas av alla användare på arbetsytan. En arbetsyta är begränsad till högst 100 hemliga omfång.

Exempel

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/secrets/scopes/create \
--data @create-scope.json

create-scope.json:

{
  "scope": "my-simple-databricks-scope",
  "initial_manage_principal": "users"
}

Ersätt:

  • <databricks-instance> med instansnamnet för Azure Databricks-arbetsytan, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • Innehållet i create-scope.json med fält som är lämpliga för din lösning.

I det här exemplet används en .netrc-fil .

Genererar RESOURCE_ALREADY_EXISTS om det redan finns ett omfång med det angivna namnet. Utlöser RESOURCE_LIMIT_EXCEEDED om det maximala antalet omfång på arbetsytan överskrids. Utlöser INVALID_PARAMETER_VALUE om omfångsnamnet är ogiltigt.

Begärandestruktur

Fältnamn Typ Description
omfång STRING Omfångsnamn som begärs av användaren. Omfångsnamn är unika. Det här fältet är obligatoriskt.
initial_manage_principal STRING Det här fältet är valfritt. Om det inte anges beviljas MANAGE endast API-begärandeutfärdarens identitet behörigheter för det nya omfånget. Om strängen users anges beviljas MANAGE alla användare på arbetsytan behörigheter.

Ta bort hemlighetsomfång

Slutpunkt HTTP-metod
2.0/secrets/scopes/delete POST

Ta bort ett hemligt omfång.

Exempel

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/secrets/scopes/delete \
--data @delete-scope.json

delete-scope.json:

{
  "scope": "my-secret-scope"
}

Ersätt:

  • <databricks-instance> med instansnamnet för Azure Databricks-arbetsytan, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • Innehållet i delete-scope.json med fält som är lämpliga för din lösning.

I det här exemplet används en .netrc-fil .

Genererar RESOURCE_DOES_NOT_EXIST om omfånget inte finns. Genererar PERMISSION_DENIED om användaren inte har behörighet att göra det här API-anropet.

Begärandestruktur

Fältnamn Typ Description
omfång STRING Namnet på omfånget som ska tas bort. Det här fältet är obligatoriskt.

Lista hemliga omfång

Slutpunkt HTTP-metod
2.0/secrets/scopes/list GET

Visa en lista över alla hemliga omfång som är tillgängliga på arbetsytan.

Exempel

Förfrågan

curl --netrc --request GET \
https://<databricks-instance>/api/2.0/secrets/scopes/list \
| jq .

Ersätt <databricks-instance> med instansnamnet för Azure Databricks-arbetsytan, till exempel adb-1234567890123456.7.azuredatabricks.net.

I det här exemplet används en .netrc-fil och jq.

Svarsåtgärder

{
  "scopes": [
    {
      "name": "my-databricks-scope",
      "backend_type": "DATABRICKS"
    },
    {
      "name": "mount-points",
      "backend_type": "DATABRICKS"
    }
  ]
}

Genererar PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.

Svarsstruktur

Fältnamn Typ Description
scopes En matris med SecretScope De tillgängliga hemliga omfången.

Placera hemlighet

Metoden för att skapa eller ändra en hemlighet beror på typen av omfångsserverdel. Om du vill skapa eller ändra en hemlighet i ett omfång som backas upp av Azure Key Vault använder du REST-API:et för Azure SetSecret. Om du vill skapa eller ändra en hemlighet från ett Databricks-backat omfång använder du följande slutpunkt:

Slutpunkt HTTP-metod
2.0/secrets/put POST

Infoga en hemlighet under det angivna omfånget med det angivna namnet. Om det redan finns en hemlighet med samma namn skriver det här kommandot över den befintliga hemlighetens värde. Servern krypterar hemligheten med hjälp av krypteringsinställningarna för det hemliga omfånget innan den lagras. Du måste ha WRITE eller MANAGE behörighet för det hemliga omfånget.

Den hemliga nyckeln måste bestå av alfanumeriska tecken, bindestreck, understreck och punkter och får inte överstiga 128 tecken. Den maximala tillåtna hemliga värdestorleken är 128 kB. Det maximala antalet hemligheter i ett visst omfång är 1 000.

Du kan bara läsa ett hemligt värde från ett kommando i ett kluster (till exempel via en notebook-fil). det finns inget API för att läsa ett hemligt värde utanför ett kluster. Den behörighet som tillämpas baseras på vem som anropar kommandot och du måste ha minst READ behörighet.

Exempel

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/secrets/put \
--data @put-secret.json

put-secret.json:

{
  "scope": "my-databricks-scope",
  "key": "my-string-key",
  "string_value": "my-value"
}

Ersätt:

  • <databricks-instance> med instansnamnet för Azure Databricks-arbetsytan, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • Innehållet i put-secret.json med fält som är lämpliga för din lösning.

I det här exemplet används en .netrc-fil .

Indatafälten "string_value" eller "bytes_value" anger typen av hemlighet, som avgör vilket värde som returneras när det hemliga värdet begärs. Exakt ett måste anges.

Genererar RESOURCE_DOES_NOT_EXIST om det inte finns något sådant hemligt omfång. Utlöser RESOURCE_LIMIT_EXCEEDED om det maximala antalet hemligheter i omfånget överskrids. Genererar INVALID_PARAMETER_VALUE om nyckelnamnet eller värdelängden är ogiltig. Genererar PERMISSION_DENIED om användaren inte har behörighet att göra det här API-anropet.

Begärandestruktur

Fältnamn Typ Description
string_value ELLER bytes_value STRING ELLER BYTES Om string_value, om det anges, lagras värdet i UTF-8-formulär (MB4).

Om bytes_value, om det anges, lagras värdet som byte.
omfång STRING Namnet på det omfång som hemligheten ska associeras med. Det här fältet är obligatoriskt.
key STRING Ett unikt namn för att identifiera hemligheten. Det här fältet är obligatoriskt.

Ta bort hemlighet

Metoden för att ta bort en hemlighet beror på typen av omfångsserverdel. Om du vill ta bort en hemlighet från ett omfång som stöds av Azure Key Vault använder du REST-API:et för Azure SetSecret. Om du vill ta bort en hemlighet från ett Databricks-backat omfång använder du följande slutpunkt:

Slutpunkt HTTP-metod
2.0/secrets/delete POST

Ta bort hemligheten som lagras i det här hemliga omfånget. Du måste ha WRITE eller MANAGE behörighet för det hemliga omfånget.

Exempel

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/secrets/delete \
--data @delete-secret.json

delete-secret.json:

{
  "scope": "my-secret-scope",
  "key": "my-secret-key"
}

Ersätt:

  • <databricks-instance> med instansnamnet för Azure Databricks-arbetsytan, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • Innehållet i delete-secret.json med fält som är lämpliga för din lösning.

I det här exemplet används en .netrc-fil .

Genererar RESOURCE_DOES_NOT_EXIST om det inte finns något sådant hemligt omfång eller hemlighet. Genererar PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.

Begärandestruktur

Fältnamn Typ Description
omfång STRING Namnet på omfånget som innehåller hemligheten som ska tas bort. Det här fältet är obligatoriskt.
key STRING Namnet på hemligheten som ska tas bort. Det här fältet är obligatoriskt.

Lista hemligheter

Slutpunkt HTTP-metod
2.0/secrets/list GET

Ange de hemliga nycklar som lagras i det här omfånget. Det här är en åtgärd som endast gäller metadata. du kan inte hämta hemliga data med hjälp av det här API:et. Du måste ha READ behörighet att göra det här anropet.

Exempel

Förfrågan

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/secrets/list?scope=<scope-name>' \
| jq .

Eller:

curl --netrc --get \
https://<databricks-instance>/api/2.0/secrets/list \
--data scope=<scope-name> \
| jq .

Ersätt:

  • <databricks-instance> med instansnamnet för Azure Databricks-arbetsytan, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • <scope-name> med namnet på hemlighetsomfånget, till exempel my-scope.

I det här exemplet används en .netrc-fil och jq.

Svarsåtgärder

{
  "secrets": [
    {
      "key": "my-string-key",
      "last_updated_timestamp": 1520467595000
    },
    {
      "key": "my-byte-key",
      "last_updated_timestamp": 1520467595000
    }
  ]
}

Den last_updated_timestamp returneras är i millisekunder sedan epoken.

Genererar RESOURCE_DOES_NOT_EXIST om det inte finns något sådant hemligt omfång. Genererar PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.

Begärandestruktur

Fältnamn Typ Description
omfång STRING Namnet på omfånget vars hemligheter du vill lista. Det här fältet är obligatoriskt.

Svarsstruktur

Fältnamn Typ Description
secrets En matris med SecretMetadata Metadatainformation för alla hemligheter som ingår i det angivna omfånget.

Placera hemlig ACL

Slutpunkt HTTP-metod
2.0/secrets/acls/put POST

Skapa eller skriv över den ACL som är associerad med det angivna huvudkontot (användare, tjänstens huvudnamn eller grupp) på den angivna omfångspunkten. I allmänhet använder en användare, tjänstens huvudnamn eller grupp den mest kraftfulla behörighet som är tillgänglig för dem, och behörigheterna sorteras på följande sätt:

  • MANAGE – Tillåts att ändra ACL:er och läsa och skriva till det här hemlighetsomfånget.
  • WRITE – Tillåts läsa och skriva till det här hemlighetsomfånget.
  • READ – Tillåts att läsa det här hemlighetsomfånget och lista vilka hemligheter som är tillgängliga.

Du måste ha behörighet att anropa det här API:et MANAGE .

Exempel

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/secrets/acls/put \
--data @put-secret-acl.json

put-secret-acl.json:

{
  "scope": "my-secret-scope",
  "principal": "data-scientists",
  "permission": "READ"
}

Ersätt:

  • <databricks-instance> med namnet på Azure Databricks-arbetsytans instans, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • Innehållet i put-secret-acl.json med fält som är lämpliga för din lösning.

I det här exemplet används en .netrc-fil .

Fältet principal anger ett befintligt Azure Databricks-huvudnamn som ska beviljas eller återkallas med hjälp av den unika identifieraren för det huvudkontot. En användare anges med sin e-post, ett huvudnamn för tjänsten med dess applicationId värde och en grupp med dess gruppnamn.

Utlöser RESOURCE_DOES_NOT_EXIST om det inte finns något sådant hemligt omfång. Utlöser RESOURCE_ALREADY_EXISTS om det redan finns en behörighet för huvudkontot. Utlöser INVALID_PARAMETER_VALUE om behörigheten är ogiltig. Utlöser PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.

Struktur för begäranden

Fältnamn Typ Description
omfång STRING Namnet på det omfång som behörigheter ska tillämpas på. Det här fältet är obligatoriskt.
Främsta STRING Det huvudkonto som behörigheten tillämpas på. Det här fältet är obligatoriskt.
Tillstånd AclPermission Behörighetsnivån som tillämpas på huvudkontot. Det här fältet är obligatoriskt.

Ta bort hemlig ACL

Slutpunkt HTTP-metod
2.0/secrets/acls/delete POST

Ta bort den angivna ACL:en för det angivna omfånget.

Du måste ha behörighet att anropa det här API:et MANAGE .

Exempel

curl --netrc --request POST \
https://<databricks-instance>/api/2.0/secrets/acls/delete \
--data @delete-secret-acl.json

delete-secret-acl.json:

{
  "scope": "my-secret-scope",
  "principal": "data-scientists"
}

Ersätt:

  • <databricks-instance> med namnet på Azure Databricks-arbetsytans instans, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • Innehållet i delete-secret-acl.json med fält som är lämpliga för din lösning.

I det här exemplet används en .netrc-fil .

Utlöser RESOURCE_DOES_NOT_EXIST om det inte finns något sådant hemligt omfång, huvudnamn eller ACL. Utlöser PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.

Struktur för begäranden

Fältnamn Typ Description
omfång STRING Namnet på omfånget som behörigheterna ska tas bort från. Det här fältet är obligatoriskt.
Främsta STRING Huvudkontot för att ta bort en befintlig ACL från. Det här fältet är obligatoriskt.

Hämta hemlig ACL

Slutpunkt HTTP-metod
2.0/secrets/acls/get GET

Beskriv informationen om den angivna ACL:en, till exempel gruppen och behörigheten.

Du måste ha behörighet att anropa det här API:et MANAGE .

Exempel

Förfrågan

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/secrets/acls/get?scope=<scope-name>&principal=<principal-name>' \
| jq .

Eller:

curl --netrc --get \
https://<databricks-instance>/api/2.0/secrets/acls/get \
--data 'scope=<scope-name>&principal=<principal-name>' \
| jq .

Ersätt:

  • <databricks-instance> med namnet på Azure Databricks-arbetsytans instans, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • <scope-name> med namnet på hemlighetsomfånget, till exempel my-scope.
  • <principal-name> med namnet på huvudkontot, till exempel users.

I det här exemplet används en .netrc-fil och jq.

Svarsåtgärder

{
  "principal": "data-scientists",
  "permission": "READ"
}

Utlöser RESOURCE_DOES_NOT_EXIST om det inte finns något sådant hemligt omfång. Utlöser PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.

Struktur för begäranden

Fältnamn Typ Description
omfång STRING Namnet på omfånget som ACL-information ska hämtas från. Det här fältet är obligatoriskt.
Främsta STRING Huvudkontot som ACL-information ska hämtas för. Det här fältet är obligatoriskt.

Svarsstruktur

Fältnamn Typ Description
Främsta STRING Det huvudkonto som behörigheten tillämpas på. Det här fältet är obligatoriskt.
Tillstånd AclPermission Behörighetsnivån som tillämpas på huvudkontot. Det här fältet är obligatoriskt.

Lista hemlighets-ACL:er

Slutpunkt HTTP-metod
2.0/secrets/acls/list GET

Visa en lista över ACL:er som angetts för det angivna omfånget.

Du måste ha behörighet att anropa det här API:et MANAGE .

Exempel

Förfrågan

curl --netrc --request GET \
'https://<databricks-instance>/api/2.0/secrets/acls/list?scope=<scope-name>' \
| jq .

Eller:

curl --netrc --get \
https://<databricks-instance>/api/2.0/secrets/acls/list \
--data scope=<scope-name> \
| jq .

Ersätt:

  • <databricks-instance> med instansnamnet för Azure Databricks-arbetsytan, till exempel adb-1234567890123456.7.azuredatabricks.net.
  • <scope-name> med namnet på hemlighetsomfånget, till exempel my-scope.

I det här exemplet används en .netrc-fil och jq.

Svarsåtgärder

{
  "items": [
    {
      "principal": "admins",
      "permission": "MANAGE"
    },
    {
      "principal": "data-scientists",
      "permission": "READ"
    }
  ]
}

Genererar RESOURCE_DOES_NOT_EXIST om det inte finns något sådant hemligt omfång. Genererar PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.

Begärandestruktur

Fältnamn Typ Description
omfång STRING Namnet på omfånget som ACL-information ska hämtas från. Det här fältet är obligatoriskt.

Svarsstruktur

Fältnamn Typ Description
objekt En matris med AclItem Den associerade ACL-regeln som tillämpas på huvudkonton i det angivna omfånget.

Datastrukturer

I det här avsnittet:

AclItem

Ett objekt som representerar en ACL-regel som tillämpas på det angivna huvudnamnet (användare, tjänstens huvudnamn eller grupp) på den associerade omfångspunkten.

Fältnamn Typ Description
Främsta STRING Det huvudnamn som behörigheten tillämpas på. Det här fältet är obligatoriskt.
Tillstånd AclPermission Behörighetsnivån som tillämpas på huvudkontot. Det här fältet är obligatoriskt.

SecretMetadata

Metadata om en hemlighet. Returneras när hemligheter listas. Innehåller inte det faktiska hemliga värdet.

Fältnamn Typ Description
key STRING Ett unikt namn för att identifiera hemligheten.
last_updated_timestamp INT64 Den senast uppdaterade tidsstämpeln (i millisekunder) för hemligheten.

SecretScope

En organisationsresurs för lagring av hemligheter. Hemliga omfång kan vara olika typer och ACL:er kan tillämpas på kontrollbehörigheter för alla hemligheter inom ett omfång.

Fältnamn Typ Description
name STRING Ett unikt namn för att identifiera det hemliga omfånget.
backend_type ScopeBackendType Typ av serverdel för hemligt omfång.

AclPermission

ACL-behörighetsnivåer för hemliga ACL:er som tillämpas på hemliga omfång.

Behörighet Description
LÄSA Tillåts utföra läsåtgärder (hämta, lista) på hemligheter i det här omfånget.
SKRIVA Tillåts att läsa och skriva hemligheter till det här hemliga omfånget.
HANTERA Tillåts läsa/skriva ACL:er och läsa/skriva hemligheter till det här hemliga omfånget.

ScopeBackendType

Typ av serverdel för hemligt omfång.

Typ Description
AZURE_KEYVAULT Ett hemligt omfång där hemligheter lagras i en Azure-Key Vault.
DATABRICKS Ett hemligt omfång där hemligheter lagras i Databricks-hanterad lagring och krypteras med en molnbaserad specifik krypteringsnyckel.