Geheimen-API 2.0

Met de Geheimen-API kunt u geheimen, geheime bereiken en toegangsmachtigingen beheren. Als u geheimen wilt beheren, moet u het volgende doen:

  1. Maak een geheim bereik.
  2. Voeg uw geheimen toe aan het bereik.
  3. Als u de Azure Databricks Premium hebt,wijst u toegangsbeheer toe aan het geheime bereik.

Zie Geheimbeheer voor meer informatie over het maken en beheren van geheimen. U kunt geheimen openen en hier naar verwijzen in notebooks en taken met behulp van het hulpprogramma Geheimen (dbutils.secrets).

Belangrijk

U moet u verifiëren voor toegang tot Databricks-REST API's. Als u de Geheimen-API wilt gebruiken Azure Key Vault geheimen, moet u verifiëren met behulp van Azure Active Directory token.

Geheim bereik maken

Eindpunt HTTP-methode
2.0/secrets/scopes/create POST

U hebt de volgende mogelijkheden:

  • Maak een Azure Key Vault bereik waarin geheimen worden opgeslagen in door Azure beheerde opslag en worden versleuteld met een cloudspecifieke versleutelingssleutel.
  • Maak een geheim bereik met Databricks-back-end waarin geheimen worden opgeslagen in door Databricks beheerde opslag en versleuteld met een cloudgebaseerde specifieke versleutelingssleutel.

Een Azure Key Vault bereik maken

De naam van het bereik:

  • Moet uniek zijn binnen een werkruimte.
  • Moet bestaan uit alfanumerieke tekens, streepjes, onderstrepingstekens en punten en mag niet langer zijn dan 128 tekens.

De namen worden beschouwd als niet-gevoelig en kunnen worden gelezen door alle gebruikers in de werkruimte. Een werkruimte is standaard beperkt tot maximaal 100 geheime scopes. Neem contact op met uw Databricks-vertegenwoordiger om dit maximum voor een werkruimte te verhogen.

Voorbeeld

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

Vervang:

In dit voorbeeld wordt een .netrc-bestand gebruikt.

Als is opgegeven, wordt de initiële ACL die wordt toegepast op het bereik, toegepast op de opgegeven principal (gebruiker of initial_manage_principal groep) met MANAGE machtigingen. De enige ondersteunde principal voor deze optie is de groep users , die alle gebruikers in de werkruimte bevat. Als niet is opgegeven, wordt de initiële ACL met de machtiging die is toegepast op het bereik toegewezen aan de gebruikersidentiteit van de vergever van de initial_manage_principalMANAGE API-aanvraag.

Wordt gegeven RESOURCE_ALREADY_EXISTS als er al een bereik met de opgegeven naam bestaat. Throws RESOURCE_LIMIT_EXCEEDED if maximum number of scopes in the workspace is exceeded. Wordt gegeven INVALID_PARAMETER_VALUE als de naam van het bereik ongeldig is.

Zie Create an Azure Key Vault-backed secret scope using the Databricks CLI(Een geheim bereik Azure Key Vault met databricks-cli) voor meer informatie.

Een geheim bereik maken dat door Databricks wordt ondersteund

De naam van het bereik:

  • Moet uniek zijn binnen een werkruimte.
  • Moet bestaan uit alfanumerieke tekens, streepjes, onderstrepingstekens en punten en mag niet langer zijn dan 128 tekens.

De namen worden beschouwd als niet-gevoelig en kunnen worden gelezen door alle gebruikers in de werkruimte. Een werkruimte is beperkt tot maximaal 100 geheime scopes.

Voorbeeld

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

Vervang:

  • <databricks-instance> met de Azure Databricks <databricks-instance>bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • De inhoud van create-scope.json met velden die geschikt zijn voor uw oplossing.

In dit voorbeeld wordt een .netrc-bestand gebruikt.

Als is opgegeven, wordt de initiële ACL die wordt toegepast op het bereik, toegepast op de opgegeven principal (gebruiker of initial_manage_principal groep) met MANAGE machtigingen. De enige ondersteunde principal voor deze optie is de groep users , die alle gebruikers in de werkruimte bevat. Als niet is opgegeven, wordt de initiële ACL met de machtiging die is toegepast op het bereik toegewezen aan de gebruikersidentiteit van de vergever van de initial_manage_principalMANAGE API-aanvraag.

Wordt gegeven RESOURCE_ALREADY_EXISTS als er al een bereik met de opgegeven naam bestaat. Throws RESOURCE_LIMIT_EXCEEDED if maximum number of scopes in the workspace is exceeded. Wordt gegeven INVALID_PARAMETER_VALUE als de naam van het bereik ongeldig is.

Aanvraagstructuur

Veldnaam Type Description
scope STRING Bereiknaam die is aangevraagd door de gebruiker. Bereiknamen zijn uniek. Dit veld is vereist.
initial_manage_principal STRING De principal die in eerste instantie toestemming krijgt MANAGE voor het gemaakte bereik.

Geheim bereik verwijderen

Eindpunt HTTP-methode
2.0/secrets/scopes/delete POST

Verwijder een geheim bereik.

Voorbeeld

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

delete-scope.json:

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

Vervang:

  • <databricks-instance> met de Azure Databricks <databricks-instance>bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • De inhoud van delete-scope.json met velden die geschikt zijn voor uw oplossing.

In dit voorbeeld wordt een .netrc-bestand gebruikt.

Wordt als RESOURCE_DOES_NOT_EXIST het bereik niet bestaat. Wordt gegeven PERMISSION_DENIED als de gebruiker geen machtiging heeft om deze API-aanroep te maken.

Aanvraagstructuur

Veldnaam Type Description
scope STRING Naam van het bereik dat moet worden verwijderd. Dit veld is vereist.

Geheime scopes op een lijst zetten

Eindpunt HTTP-methode
2.0/secrets/scopes/list GET

Een lijst met alle geheime scopes die beschikbaar zijn in de werkruimte.

Voorbeeld

Aanvraag

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

Vervang <databricks-instance> door de naam Azure Databricks <databricks-instance>, bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .

In dit voorbeeld wordt een .netrc-bestand en jq gebruikt.

Antwoord

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

Wordt gegeven PERMISSION_DENIED als u geen machtiging hebt om deze API-aanroep te maken.

Antwoordstructuur

Veldnaam Type Description
bereiken Een matrix van SecretScope De beschikbare geheime scopes.

Geheim maken

De methode voor het maken of wijzigen van een geheim is afhankelijk van het type scope-back-end. Als u een geheim wilt maken of wijzigen in een bereik dat wordt Azure Key Vault, gebruikt u de Azure SetSecret-REST API. Als u een geheim wilt maken of wijzigen vanuit een bereik met Databricks-back-end, gebruikt u het volgende eindpunt:

Eindpunt HTTP-methode
2.0/secrets/put POST

Voeg een geheim in onder het opgegeven bereik met de opgegeven naam. Als er al een geheim met dezelfde naam bestaat, overschrijft deze opdracht de waarde van het bestaande geheim. De server versleutelt het geheim met behulp van de versleutelingsinstellingen van het geheime bereik voordat het wordt opgeslagen. U moet de WRITE machtiging of hebben voor het geheime MANAGE bereik.

De geheime sleutel moet bestaan uit alfanumerieke tekens, streepjes, onderstrepingstekens en punten en mag niet langer zijn dan 128 tekens. De maximaal toegestane grootte van de geheime waarde is 128 kB. Het maximum aantal geheimen in een bepaald bereik is 1000.

U kunt een geheime waarde alleen lezen vanuit een opdracht in een cluster (bijvoorbeeld via een notebook); er is geen API om een geheime waarde buiten een cluster te lezen. De toegepaste machtiging is gebaseerd op wie de opdracht aanroept en u moet ten minste READ machtigingen hebben.

Voorbeeld

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

Vervang:

  • <databricks-instance> met de Azure Databricks <databricks-instance>bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • De inhoud van put-secret.json met velden die geschikt zijn voor uw oplossing.

In dit voorbeeld wordt een .netrc-bestand gebruikt.

De invoervelden 'string_value' of 'bytes_value' geven het type geheim op, waarmee de waarde wordt bepaald die wordt geretourneerd wanneer de geheime waarde wordt aangevraagd. Er moet precies één worden opgegeven.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Throws RESOURCE_LIMIT_EXCEEDED if maximum number of secrets in scope is exceeded. Wordt gegeven INVALID_PARAMETER_VALUE als de sleutelnaam of waardelengte ongeldig is. Wordt gegeven PERMISSION_DENIED als de gebruiker geen machtiging heeft om deze API-aanroep te maken.

Aanvraagstructuur

Veldnaam Type Description
string_value OF bytes_value STRING OF BYTES Als string_value, indien opgegeven, wordt de waarde opgeslagen in de vorm UTF-8 (MB4).

Als bytes_value, indien opgegeven, wordt de waarde opgeslagen als bytes.
scope STRING De naam van het bereik waaraan het geheim wordt gekoppeld. Dit veld is vereist.
sleutel STRING Een unieke naam om het geheim te identificeren. Dit veld is vereist.

Geheim verwijderen

De methode voor het verwijderen van een geheim is afhankelijk van het type scope-back-end. Als u een geheim wilt verwijderen uit een bereik dat wordt Azure Key Vault, gebruikt u de Azure SetSecret-REST API. Als u een geheim wilt verwijderen uit een bereik met Databricks-back-end, gebruikt u het volgende eindpunt:

Eindpunt HTTP-methode
2.0/secrets/delete POST

Verwijder het geheim dat is opgeslagen in dit geheime bereik. U moet de WRITE machtiging of hebben voor het geheime MANAGE bereik.

Voorbeeld

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

Vervang:

  • <databricks-instance> met de Azure Databricks <databricks-instance>bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • De inhoud van delete-secret.json met velden die geschikt zijn voor uw oplossing.

In dit voorbeeld wordt een .netrc-bestand gebruikt.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope or secret exists. Wordt gegeven PERMISSION_DENIED als u geen machtiging hebt om deze API-aanroep te maken.

Aanvraagstructuur

Veldnaam Type Description
scope STRING De naam van het bereik dat het geheim bevat dat moet worden verwijderd. Dit veld is vereist.
sleutel STRING Naam van het geheim dat moet worden verwijderd. Dit veld is vereist.

Geheimen op een lijst zetten

Eindpunt HTTP-methode
2.0/secrets/list GET

Hiermee worden de geheime sleutels weergegeven die in dit bereik zijn opgeslagen. Dit is een bewerking met alleen metagegevens; u kunt geen geheime gegevens ophalen met behulp van deze API. U moet toestemming READ hebben om deze aanroep te doen.

Voorbeeld

Aanvraag

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

Of:

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

Vervang:

  • <databricks-instance> met de Azure Databricks <databricks-instance>bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • <scope-name> door de naam van het geheimenbereik, bijvoorbeeld my-scope .

In dit voorbeeld wordt een .netrc-bestand en jq gebruikt.

Antwoord

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

De last_updated_timestamp geretourneerd, is in milliseconden sinds epoche.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Wordt gegeven PERMISSION_DENIED als u geen machtiging hebt om deze API-aanroep te maken.

Aanvraagstructuur

Veldnaam Type Description
scope STRING De naam van het bereik waarvan u de geheimen wilt noemen. Dit veld is vereist.

Antwoordstructuur

Veldnaam Type Description
geheimen Een matrix van SecretMetadata Metagegevens van alle geheimen binnen het opgegeven bereik.

Geheime ACL zetten

Eindpunt HTTP-methode
2.0/secrets/acls/put POST

Maak of overschrijf de ACL die is gekoppeld aan de opgegeven principal (gebruiker of groep) op het opgegeven bereikpunt. Over het algemeen gebruikt een gebruiker of groep de krachtigste machtiging die voor hen beschikbaar is en worden de machtigingen als volgt geordend:

  • MANAGE - Mag ACL's wijzigen en lezen en schrijven naar dit geheime bereik.
  • WRITE - Mag lezen en schrijven naar dit geheime bereik.
  • READ - Toegestaan om dit geheime bereik te lezen en te zien welke geheimen beschikbaar zijn.

U moet de machtiging hebben MANAGE om deze API aan te roepen.

Voorbeeld

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

Vervang:

  • <databricks-instance> door de naam Azure Databricks <databricks-instance>, bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • De inhoud van put-secret-acl.json met velden die geschikt zijn voor uw oplossing.

In dit voorbeeld wordt een .netrc-bestand gebruikt.

De principal is een naam van een gebruiker of groep die overeenkomt met een bestaande Azure Databricks-principal die moet worden verleend of ingetrokken.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Wordt gegeven RESOURCE_ALREADY_EXISTS als er al een machtiging voor de principal bestaat. Wordt gegeven INVALID_PARAMETER_VALUE als de machtiging ongeldig is. Wordt gegeven PERMISSION_DENIED als u geen machtiging hebt om deze API-aanroep te maken.

Aanvraagstructuur

Veldnaam Type Description
scope STRING De naam van het bereik waar machtigingen op moeten worden toegepast. Dit veld is vereist.
Belangrijkste STRING De principal waarop de machtiging wordt toegepast. Dit veld is vereist.
Toestemming AclPermission Het machtigingsniveau dat wordt toegepast op de principal. Dit veld is vereist.

Geheime ACL verwijderen

Eindpunt HTTP-methode
2.0/secrets/acls/delete POST

Verwijder de opgegeven ACL voor het opgegeven bereik.

U moet de machtiging hebben MANAGE om deze API aan te roepen.

Voorbeeld

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

Vervang:

  • <databricks-instance> door de naam Azure Databricks <databricks-instance>, bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • De inhoud van delete-secret-acl.json met velden die geschikt zijn voor uw oplossing.

In dit voorbeeld wordt een .netrc-bestand gebruikt.

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope, principal, or ACL exists. Wordt gegeven PERMISSION_DENIED als u geen machtiging hebt om deze API-aanroep te maken.

Aanvraagstructuur

Veldnaam Type Description
scope STRING De naam van het bereik waar machtigingen uit moeten worden verwijderd. Dit veld is vereist.
Belangrijkste STRING De principal waar een bestaande ACL uit moet worden verwijderd. Dit veld is vereist.

Geheime ACL op halen

Eindpunt HTTP-methode
2.0/secrets/acls/get GET

Beschrijf de details van de opgegeven ACL, zoals de groep en machtiging.

U moet de machtiging hebben MANAGE om deze API aan te roepen.

Voorbeeld

Aanvraag

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

Of:

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

Vervang:

  • <databricks-instance> door de naam Azure Databricks <databricks-instance>, bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • <scope-name> door de naam van het geheimenbereik, bijvoorbeeld my-scope .
  • <principal-name> door de naam van de principal, bijvoorbeeld users .

In dit voorbeeld wordt een .netrc-bestand en jq gebruikt.

Antwoord

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

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Wordt gegeven PERMISSION_DENIED als u geen machtiging hebt om deze API-aanroep te maken.

Aanvraagstructuur

Veldnaam Type Description
scope STRING De naam van het bereik waar ACL-gegevens uit moeten worden opgehaald. Dit veld is vereist.
Belangrijkste STRING De principal voor het ophalen van ACL-gegevens voor. Dit veld is vereist.

Antwoordstructuur

Veldnaam Type Description
Belangrijkste STRING De principal waarop de machtiging wordt toegepast. Dit veld is vereist.
Toestemming AclPermission Het machtigingsniveau dat wordt toegepast op de principal. Dit veld is vereist.

Geheime ACL's opsnl's

Eindpunt HTTP-methode
2.0/secrets/acls/list GET

Vermeld de ACL's die zijn ingesteld voor het opgegeven bereik.

U moet de machtiging hebben MANAGE om deze API aan te roepen.

Voorbeeld

Aanvraag

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

Of:

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

Vervang:

  • <databricks-instance> door de naam Azure Databricks <databricks-instance>, bijvoorbeeld adb-1234567890123456.7.azuredatabricks.net .
  • <scope-name> door de naam van het geheimenbereik, bijvoorbeeld my-scope .

In dit voorbeeld wordt een .netrc-bestand en jq gebruikt.

Antwoord

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

Throws RESOURCE_DOES_NOT_EXIST if no such secret scope exists. Wordt gegeven PERMISSION_DENIED als u geen machtiging hebt om deze API-aanroep te maken.

Aanvraagstructuur

Veldnaam Type Description
scope STRING De naam van het bereik waar ACL-gegevens uit moeten worden opgehaald. Dit veld is vereist.

Antwoordstructuur

Veldnaam Type Description
Items Een matrix van AclItem De bijbehorende ACL-regel die wordt toegepast op principals in het opgegeven bereik.

Gegevensstructuren

In deze sectie:

AclItem

Een item dat een ACL-regel vertegenwoordigt die wordt toegepast op de opgegeven principal (gebruiker of groep) op het gekoppelde bereikpunt.

Veldnaam Type Description
Belangrijkste STRING De principal waarop de machtiging wordt toegepast. Dit veld is vereist.
Toestemming AclPermission Het machtigingsniveau dat wordt toegepast op de principal. Dit veld is vereist.

SecretMetadata

De metagegevens over een geheim. Geretourneerd bij het opslijsten van geheimen. Bevat niet de werkelijke geheime waarde.

Veldnaam Type Description
sleutel STRING Een unieke naam om het geheim te identificeren.
last_updated_timestamp INT64 Het laatst bijgewerkte tijdstempel (in milliseconden) voor het geheim.

SecretScope

Een organisatieresource voor het opslaan van geheimen. Geheime scopes kunnen verschillende typen zijn en ACL's kunnen worden toegepast om machtigingen voor alle geheimen binnen een bereik te bepalen.

Veldnaam Type Beschrijving
naam STRING Een unieke naam om het geheime bereik te identificeren.
backend_type ScopeBackendType Het type back-end van het geheime bereik.

AclPermission

De ACL-machtigingsniveaus voor geheime ACL's die zijn toegepast op geheime bereiken.

Machtiging Beschrijving
LEZEN Toegestaan om leesbewerkingen (get, list) uit te voeren op geheimen in dit bereik.
SCHRIJVEN Toegestaan om geheimen te lezen en te schrijven naar dit geheime bereik.
BEHEREN Toegestaan om ACL's te lezen/schrijven en geheimen te lezen/schrijven naar dit geheime bereik.

ScopeBackendType

Het type back-end van het geheime bereik.

Type Description
AZURE_KEYVAULT Een geheim bereik waarin geheimen worden opgeslagen in een Azure Key Vault.
DATABRICKS Een geheim bereik waarin geheimen worden opgeslagen in door Databricks beheerde opslag en worden versleuteld met een cloudspecifieke versleutelingssleutel.