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:
- Skapa en omfattning för en hemlighet.
- Lägg till dina hemligheter i omfånget.
- Om du har Premium-planentilldelar 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 secrets-API:et med Azure Key Vault hemligheter måste du autentisera med 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:
<databricks-instance>med instansnamnet för Azure Databricks-arbetsytan, till exempeladb-1234567890123456.7.azuredatabricks.net.<token>med din personliga Åtkomsttoken för Azure Databricks. Mer information finns i Autentisering med azure Databricks personliga åtkomsttoken.<management-token>med din Azure Active Directory-token. Mer information finns i Hämta Azure AD token för användare med hjälp av MSAL.- Innehållet i
create-scope.jsonmed fält som är lämpliga för din lösning.
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 exempeladb-1234567890123456.7.azuredatabricks.net.- Innehållet i
create-scope.jsonmed 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 | Beskrivning |
|---|---|---|
| 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 exempeladb-1234567890123456.7.azuredatabricks.net.- Innehållet i
delete-scope.jsonmed 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 | Beskrivning |
|---|---|---|
| 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 | Beskrivning |
|---|---|---|
| scopes | En matris med SecretScope | Tillgängliga hemlighetsomfång. |
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-stödt 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 hemlighetsvä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 inifrå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 namnet på Azure Databricks-arbetsytans instans, till exempeladb-1234567890123456.7.azuredatabricks.net.- Innehållet i
put-secret.jsonmed 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, vilket avgör vilket värde som returneras när det hemliga värdet begärs. Exakt ett måste anges.
Utlöser 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.
Struktur för begäranden
| Fältnamn | Typ | Beskrivning |
|---|---|---|
| string_value ELLER bytes_value | STRING ELLER BYTES |
Om string_value, om det anges, lagras värdet i UTF-8 -format (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 backas upp 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-stödt 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 hemlighetsomfå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 namnet på Azure Databricks-arbetsytans instans, till exempeladb-1234567890123456.7.azuredatabricks.net.- Innehållet i
delete-secret.jsonmed 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 eller hemlighet.
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 | Beskrivning |
|---|---|---|
| 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. |
Visa en lista över 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 med endast 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 namnet på Azure Databricks-arbetsytans instans, till exempeladb-1234567890123456.7.azuredatabricks.net.<scope-name>med namnet på hemlighetsomfånget, till exempelmy-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.
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 | Beskrivning |
|---|---|---|
| omfång | STRING |
Namnet på det omfång vars hemligheter du vill lista. Det här fältet är obligatoriskt. |
Svarsstruktur
| Fältnamn | Typ | Beskrivning |
|---|---|---|
| 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 huvudnamnet (användaren, 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 enligt följande:
MANAGE– Tillåts att ändra ACL:er och läsa och skriva till det här hemliga omfånget.WRITE– Tillåts att läsa och skriva till det här hemliga omfånget.READ– Tillåts att läsa det här hemliga omfå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 instansnamnet för Azure Databricks-arbetsytan, till exempeladb-1234567890123456.7.azuredatabricks.net.- Innehållet i
put-secret-acl.jsonmed 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 den unika identifieraren för det huvudkontot. En användare anges med e-post, ett huvudnamn för tjänsten med dess applicationId värde och en grupp med dess gruppnamn.
Genererar RESOURCE_DOES_NOT_EXIST om det inte finns något sådant hemligt omfång.
Genererar RESOURCE_ALREADY_EXISTS om det redan finns en behörighet för huvudkontot.
Utlöser INVALID_PARAMETER_VALUE om behörigheten är ogiltig.
Genererar PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.
Begärandestruktur
| Fältnamn | Typ | Beskrivning |
|---|---|---|
| omfång | STRING |
Namnet på omfånget som behörigheter ska tillämpas på. Det här fältet är obligatoriskt. |
| 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. |
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 instansnamnet för Azure Databricks-arbetsytan, till exempeladb-1234567890123456.7.azuredatabricks.net.- Innehållet i
delete-secret-acl.jsonmed 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, huvudnamn eller ACL.
Genererar PERMISSION_DENIED om du inte har behörighet att göra det här API-anropet.
Begärandestruktur
| Fältnamn | Typ | Beskrivning |
|---|---|---|
| omfång | STRING |
Namnet på omfånget för att ta bort behörigheter från. Det här fältet är obligatoriskt. |
| Främsta | STRING |
Det huvudnamn som du vill 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 instansnamnet för Azure Databricks-arbetsytan, till exempeladb-1234567890123456.7.azuredatabricks.net.<scope-name>med namnet på hemlighetsomfånget, till exempelmy-scope.<principal-name>med namnet på huvudnamnet, till exempelusers.
I det här exemplet används en .netrc-fil och jq.
Svarsåtgärder
{
"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 | Beskrivning |
|---|---|---|
| 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 |
Det huvudnamn som ACL-information ska hämtas för. Det här fältet är obligatoriskt. |
Svarsstruktur
| Fältnamn | Typ | Beskrivning |
|---|---|---|
| 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. |
Lista hemliga ACL:er
| Slutpunkt | HTTP-metod |
|---|---|
2.0/secrets/acls/list |
GET |
Ange de 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 namnet på Azure Databricks-arbetsytans instans, till exempeladb-1234567890123456.7.azuredatabricks.net.<scope-name>med namnet på hemlighetsomfånget, till exempelmy-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"
}
]
}
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 | Beskrivning |
|---|---|---|
| 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 | Beskrivning |
|---|---|---|
| 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 huvudkontot (användare, tjänstens huvudnamn eller grupp) på den associerade omfångspunkten.
| Fältnamn | Typ | Beskrivning |
|---|---|---|
| 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. |
SecretMetadata
Metadata om en hemlighet. Returneras när hemligheter listas. Innehåller inte det faktiska hemlighetsvärdet.
| Fältnamn | Typ | Beskrivning |
|---|---|---|
| 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. Hemlighetsomfå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 | Beskrivning |
|---|---|---|
| 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 | Beskrivning |
|---|---|
| LÄSA | Tillåts utföra läsåtgärder (hämta, lista) på hemligheter i det här omfånget. |
| SKRIVA | Tillåts läsa och skriva hemligheter till det här hemlighetsomfånget. |
| HANTERA | Tillåts läsa/skriva ACL:er och läsa/skriva hemligheter i det här hemlighetsomfånget. |
ScopeBackendType
Typ av serverdel för hemligt omfång.
| Typ | Beskrivning |
|---|---|
| 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. |