Wat is embedden voor externe gebruikers?

Op deze pagina wordt beschreven hoe insluiten voor externe gebruikers werkt, hoe u uw Azure Databricks werkruimte configureert voor veilig delen van ingesloten dashboards en hoe u voorbeeldtoepassingen kunt gebruiken om aan de slag te gaan. Embedding voor externe gebruikers maakt gebruik van een service-principal en toegangstokens met beperkt bereik om toegang tot ingesloten dashboards te authenticeren en te autoriseren. Met deze aanpak kunt u dashboards delen met kijkers buiten uw organisatie, zoals partners en klanten, zonder Azure Databricks accounts voor die gebruikers in te richten.

Zie Een dashboard insluiten voor meer informatie over andere opties voor insluiten, waaronder het insluiten van dashboards voor gebruikers binnen uw organisatie.

Hoe het inbedden voor externe gebruikers werkt

In de diagram- en genummerde stappen die volgen, wordt uitgelegd hoe gebruikers worden geverifieerd en dashboards worden gevuld met resultaten binnen het gebruikersbereik wanneer u een dashboard insluit voor externe gebruikers.

1. Gebruikersverificatie en -aanvraag: De gebruiker meldt zich aan bij uw toepassing. De front-end van uw toepassing verzendt een geverifieerde aanvraag naar uw server voor een dashboardtoegangstoken.
2. Verificatie van service-principal: Uw server gebruikt het geheim van de service-principal om een OAuth-token aan te vragen en te ontvangen van de Databricks-server. Dit is een breed bereiktoken dat alle dashboard-API's kan aanroepen waartoe Azure Databricks namens de service-principal toegang heeft. Uw server roept het /tokeninfo eindpunt aan met behulp van dit token, waarbij basisgebruikersgegevens worden doorgegeven, zoals external_viewer_id en external_value. Zie Dashboards veilig presenteren aan afzonderlijke gebruikers.
3. Genereren van een gebruiker-gescopeerde token: Met behulp van de respons van de /tokeninfo-endpoint en het Databricks OpenID Connect (OIDC)-endpoint genereert uw server een nieuw nauw gedefinieerd token dat de door u doorgegeven gebruikersinformatie codeert.
4. Dashboardweergave en gegevensfiltering: De toepassingspagina instantieert DatabricksDashboard van @databricks/aibi-client en geeft het gebruikersgerichte token door tijdens constructie. Het dashboard wordt weergegeven met de context van de gebruiker. Dit token autoriseert toegang, ondersteunt auditering met external_viewer_id en draagt external_value voor het filteren van gegevens. Queries in dashboarddatasets kunnen verwijzen __aibi_external_value om filters per gebruiker toe te passen, zodat elke kijker alleen gegevens ziet die zij mogen bekijken.

Ask Genie is niet beschikbaar bij extern embedden

De knop Ask Genie wordt niet ondersteund bij het insluiten van inhoud voor externe gebruikers. Als u querymogelijkheden voor gegevens in natuurlijke taal wilt bieden aan externe gebruikers, gebruikt u in plaats daarvan de Genie Conversation-API . Met de Conversation-API kunt u Genie-functionaliteit programmatisch integreren in uw toepassing, onafhankelijk van het insluiten van dashboards.

Voor dashboards met basisembedding is Ask Genie beschikbaar. Zie Ask Genie in ingesloten dashboards.

Dashboards veilig presenteren aan afzonderlijke gebruikers

Configureer uw toepassingsserver om een uniek token met gebruikersbereik te genereren voor elke gebruiker op basis van hun external_viewer_id. Hiermee kunt u dashboardweergaven en -gebruik bijhouden via auditlogboeken. Het external_viewer_id is gekoppeld aan een external_value, dat fungeert als een globale variabele die kan worden ingevoegd in SQL-query's die worden gebruikt in dashboardgegevenssets. Hiermee kunt u de gegevens filteren die worden weergegeven op het dashboard voor elke gebruiker.

external_viewer_id wordt doorgegeven aan uw dashboardcontrolelogboeken en mag geen persoonsgegevens bevatten. Deze waarde moet ook uniek zijn per gebruiker.

external_value wordt gebruikt bij het verwerken van query's en kan persoonsgegevens bevatten.

In het volgende voorbeeld ziet u hoe u de externe waarde gebruikt als filter in gegevenssetquery's:

SELECT *
FROM sales
WHERE region = __aibi_external_value

Installatieoverzicht

Deze sectie bevat een algemeen conceptueel overzicht van de stappen die u moet uitvoeren om een dashboard in te sluiten op een externe locatie.

Als u een dashboard wilt insluiten in een externe toepassing, maakt u eerst een service-principal in Azure Databricks en genereert u een geheim. De service-principal moet leestoegang krijgen tot het dashboard en de onderliggende gegevens. Uw server gebruikt het geheim van de service-principal om een token op te halen dat namens de service-principal toegang heeft tot dashboard-API's. Met dit token roept de server het /tokeninfo API-eindpunt aan, een OpenID Connect-eindpunt (OIDC) dat basisgegevens van gebruikersprofielen retourneert, inclusief de external_value en external_viewer_id waarden. Met deze waarden kunt u aanvragen koppelen aan afzonderlijke gebruikers.

Met behulp van het token dat is verkregen van de service-principal, genereert uw server een nieuw token dat is gericht op de specifieke gebruiker die toegang heeft tot het dashboard. Dit token met gebruikersbereik wordt doorgegeven aan de toepassingspagina, waarbij de toepassing het DatabricksDashboard object vanuit de @databricks/aibi-client bibliotheek instantieert. Het token bevat gebruikersspecifieke informatie die ondersteuning biedt voor controle en afdwingt filteren, zodat elke gebruiker alleen de gegevens ziet waartoe ze zijn gemachtigd. Vanuit het perspectief van de gebruiker biedt aanmelden bij de toepassing automatisch toegang tot het ingesloten dashboard met de juiste zichtbaarheid van gegevens.

Snelheidslimieten en prestatieoverwegingen

Extern insluiten heeft een ratelimiet van 20 dashboard-laadverzoeken per seconde. U kunt meer dan 20 dashboards tegelijk openen, maar er kunnen niet meer dan 20 tegelijk worden geladen.

Vereiste voorwaarden

Als u extern insluiten wilt implementeren, moet u voldoen aan de volgende vereisten:

• U moet ten minste machtigingen voor CAN MANAGE hebben op een gepubliceerd dashboard. Zie Zelfstudie: Voorbeelddashboards gebruiken om snel een voorbeelddashboard te maken en publiceren, indien nodig.
• U moet Databricks CLI versie 0.205 of hoger hebben geïnstalleerd. Zie De Databricks CLI installeren of bijwerken voor instructies. Als u OAuth-verificatie wilt configureren en gebruiken, raadpleegt u OAuth-gebruikers-naar-machine-verificatie (U2M).
• Een werkruimtebeheerder moet een lijst definiëren met goedgekeurde domeinen die het ingesloten dashboard kunnen hosten. Zie Dashboard beheren en Genie Agent insluiten voor instructies.
• Een externe toepassing voor het hosten van uw ingesloten dashboard. U kunt uw eigen toepassing gebruiken of de meegeleverde voorbeeldtoepassingen gebruiken.

Stap 1: Een service-principal maken

Maak een service-principal om te fungeren als de identiteit voor uw externe toepassing binnen Azure Databricks. Deze service-principal verifieert aanvragen namens uw toepassing.

Een service-principal aanmaken:

1. Meld u als werkruimtebeheerder aan bij de Azure Databricks werkruimte.
2. Klik op uw gebruikersnaam in de bovenste balk van de Azure Databricks werkruimte en selecteer Settings.
3. Klik op Identiteit en toegang in het linkerdeelvenster.
4. Klik naast Service-principals op Beheren.
5. Klik op Service-principal toevoegen.
6. Klik op Nieuwe toevoegen.
7. Voer een beschrijvende naam in voor de service-principal.
8. Klik op Toevoegen.
9. Open de service-principal die u zojuist hebt gemaakt van de overzichtspagina Service-principals. Gebruik indien nodig het invoerveld Tekst filteren om ernaar te zoeken op naam.
10. Noteer de Application Id op de pagina Service principal details. Controleer of de selectievakjes voor Databricks SQL-toegang en Werkruimtetoegang zijn ingeschakeld.

Stap 2: Een OAuth-geheim maken

Genereer een geheim voor de service-principal en verzamel de volgende configuratiewaarden die u nodig hebt voor uw externe toepassing:

• Id van service-principal (client)
• Clientgeheim

De service-principal gebruikt een OAuth-geheim om de identiteit te verifiëren bij het aanvragen van een toegangstoken vanuit uw externe toepassing.

Een geheim genereren:

1. Klik op Geheimen op de pagina Service Principal Details.
2. Klik op Geheim genereren.
3. Voer een levensduurwaarde in voor het nieuwe geheim in dagen (bijvoorbeeld tussen 1 en 730 dagen).
4. Kopieer het geheim onmiddellijk. U kunt dit geheim niet meer weergeven nadat u dit scherm hebt verlaten.

Stap 3: Machtigingen toewijzen aan uw service-principal

De service-principal die u hebt gemaakt, fungeert als de identiteit die dashboardtoegang biedt via uw toepassing. De machtigingen zijn alleen van toepassing als het dashboard niet wordt gepubliceerd met gedeelde gegevensmachtigingen. Als gedeelde gegevensmachtigingen worden gebruikt, hebben de referenties van de uitgever toegang tot gegevens. Zie De verificatiemethoden insluiten voor meer informatie en aanbevelingen.

1. Klik op Dashboards in de zijbalk van de werkruimte om de pagina met dashboardvermeldingen te openen.
2. Klik op de naam van het dashboard dat u wilt insluiten. Het gepubliceerde dashboard wordt geopend.
3. Klik op delen.
4. Gebruik het tekstinvoerveld in het dialoogvenster Delen om uw service-principal te vinden en klik erop. Stel het machtigingsniveau in op CAN RUN. Klik vervolgens op Toevoegen.
5. Registreer de Dashboard-ID. U vindt de dashboard-id in de URL van het dashboard (bijvoorbeeld https://<your-workspace-url>/dashboards/<dashboard-id>). Zie de details van de Databricks-werkruimte.

Stap 4: De voorbeeld-app gebruiken om tokens te verifiëren en te genereren

Gebruik een voorbeeldapplicatie om uw dashboard extern in te bedden. De toepassingen bevatten instructies en code waarmee de benodigde tokenuitwisseling wordt gestart om scoped tokens te genereren. De volgende codeblokken hebben geen afhankelijkheden. Kopieer en sla een van de volgende toepassingen op.

Python

Kopieer en sla dit op in een bestand met de naam example.py.

#!/usr/bin/env python3

import os
import sys
import json
import base64
import urllib.request
import urllib.parse
from http.server import HTTPServer, BaseHTTPRequestHandler

# -----------------------------------------------------------------------------
# Config
# -----------------------------------------------------------------------------
CONFIG = {
    "instance_url": os.environ.get("INSTANCE_URL"),
    "dashboard_id": os.environ.get("DASHBOARD_ID"),
    "service_principal_id": os.environ.get("SERVICE_PRINCIPAL_ID"),
    "service_principal_secret": os.environ.get("SERVICE_PRINCIPAL_SECRET"),
    "external_viewer_id": os.environ.get("EXTERNAL_VIEWER_ID"),
    "external_value": os.environ.get("EXTERNAL_VALUE"),
    "workspace_id": os.environ.get("WORKSPACE_ID"),
    "port": int(os.environ.get("PORT", 3000)),
}

basic_auth = base64.b64encode(
    f"{CONFIG['service_principal_id']}:{CONFIG['service_principal_secret']}".encode()
).decode()

# -----------------------------------------------------------------------------
# HTTP Request Helper
# -----------------------------------------------------------------------------
def http_request(url, method="GET", headers=None, body=None):
    headers = headers or {}
    if body is not None and not isinstance(body, (bytes, str)):
        raise ValueError("Body must be bytes or str")

    req = urllib.request.Request(url, method=method, headers=headers)
    if body is not None:
        if isinstance(body, str):
            body = body.encode()
        req.data = body

    try:
        with urllib.request.urlopen(req) as resp:
            data = resp.read().decode()
            try:
                return {"data": json.loads(data)}
            except json.JSONDecodeError:
                return {"data": data}
    except urllib.error.HTTPError as e:
        raise RuntimeError(f"HTTP {e.code}: {e.read().decode()}") from None

# -----------------------------------------------------------------------------
# Token logic
# -----------------------------------------------------------------------------
def get_scoped_token():
    # 1. Get all-api token
    oidc_res = http_request(
        f"{CONFIG['instance_url']}/oidc/v1/token?o={CONFIG['workspace_id']}",
        method="POST",
        headers={
            "Content-Type": "application/x-www-form-urlencoded",
            "Authorization": f"Basic {basic_auth}",
        },
        body=urllib.parse.urlencode({
            "grant_type": "client_credentials",
            "scope": "all-apis"
        })
    )
    oidc_token = oidc_res["data"]["access_token"]

    # 2. Get token info
    token_info_url = (
        f"{CONFIG['instance_url']}/api/2.0/lakeview/dashboards/"
        f"{CONFIG['dashboard_id']}/published/tokeninfo"
        f"?o={CONFIG['workspace_id']}"
        f"&external_viewer_id={urllib.parse.quote(CONFIG['external_viewer_id'])}"
        f"&external_value={urllib.parse.quote(CONFIG['external_value'])}"
    )
    token_info = http_request(
        token_info_url,
        headers={"Authorization": f"Bearer {oidc_token}"}
    )["data"]

    # 3. Generate scoped token
    params = token_info.copy()
    authorization_details = params.pop("authorization_details", None)
    params.update({
        "grant_type": "client_credentials",
        "authorization_details": json.dumps(authorization_details)
    })

    scoped_res = http_request(
        f"{CONFIG['instance_url']}/oidc/v1/token?o={CONFIG['workspace_id']}",
        method="POST",
        headers={
            "Content-Type": "application/x-www-form-urlencoded",
            "Authorization": f"Basic {basic_auth}",
        },
        body=urllib.parse.urlencode(params)
    )
    return scoped_res["data"]["access_token"]

# -----------------------------------------------------------------------------
# HTML generator
# -----------------------------------------------------------------------------
def generate_html(token):
    return f"""<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dashboard Demo</title>
    <style>
        body {{ font-family: system-ui; margin: 0; padding: 20px; background: #f5f5f5; }}
        .container {{ max-width: 1200px; margin: 0 auto; height:calc(100vh - 40px) }}
    </style>
</head>
<body>
    <div id="dashboard-content" class="container"></div>
    <script type="module">
        import {{ DatabricksDashboard }} from "https://cdn.jsdelivr.net/npm/@databricks/aibi-client@0.0.0-alpha.7/+esm";
        const dashboard = new DatabricksDashboard({{
            instanceUrl: "{CONFIG['instance_url']}",
            workspaceId: "{CONFIG['workspace_id']}",
            dashboardId: "{CONFIG['dashboard_id']}",
            token: "{token}",
            container: document.getElementById("dashboard-content")
        }});
        dashboard.initialize();
    </script>
</body>
</html>"""

# -----------------------------------------------------------------------------
# HTTP server
# -----------------------------------------------------------------------------
class RequestHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path != "/":
            self.send_response(404)
            self.send_header("Content-Type", "text/plain")
            self.end_headers()
            self.wfile.write(b"Not Found")
            return

        try:
            token = get_scoped_token()
            html = generate_html(token)
            status = 200
        except Exception as e:
            html = f"<h1>Error</h1><p>{e}</p>"
            status = 500

        self.send_response(status)
        self.send_header("Content-Type", "text/html")
        self.end_headers()
        self.wfile.write(html.encode())

def start_server():
    missing = [k for k, v in CONFIG.items() if not v]
    if missing:
        print(f"Missing: {', '.join(missing)}", file=sys.stderr)
        sys.exit(1)

    server = HTTPServer(("localhost", CONFIG["port"]), RequestHandler)
    print(f":rocket: Server running on http://localhost:{CONFIG['port']}")
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        sys.exit(0)

if __name__ == "__main__":
    start_server()

JavaScript

Kopieer en sla dit op in een bestand met de naam example.js.

#!/usr/bin/env node

const http = require('http');
const https = require('https');
const { URL, URLSearchParams } = require('url');

// This constant is just a mapping of environment variables to their respective
// values.
const CONFIG = {
  instanceUrl: process.env.INSTANCE_URL,
  dashboardId: process.env.DASHBOARD_ID,
  servicePrincipalId: process.env.SERVICE_PRINCIPAL_ID,
  servicePrincipalSecret: process.env.SERVICE_PRINCIPAL_SECRET,
  externalViewerId: process.env.EXTERNAL_VIEWER_ID,
  externalValue: process.env.EXTERNAL_VALUE,
  workspaceId: process.env.WORKSPACE_ID,
  port: process.env.PORT || 3000,
};

const basicAuth = Buffer.from(`${CONFIG.servicePrincipalId}:${CONFIG.servicePrincipalSecret}`).toString('base64');

// ------------------------------------------------------------------------------------------------
// Main
// ------------------------------------------------------------------------------------------------

function startServer() {
  const missing = Object.keys(CONFIG).filter((key) => !CONFIG[key]);
  if (missing.length > 0) throw new Error(`Missing: ${missing.join(', ')}`);

  const server = http.createServer(async (req, res) => {
    // This is a demo server, we only support GET requests to the root URL.
    if (req.method !== 'GET' || req.url !== '/') {
      res.writeHead(404, { 'Content-Type': 'text/plain' });
      res.end('Not Found');
      return;
    }

    let html = '';
    let status = 200;

    try {
      const token = await getScopedToken();
      html = generateHTML(token);
    } catch (error) {
      html = `<h1>Error</h1><p>${error.message}</p>`;
      status = 500;
    } finally {
      res.writeHead(status, { 'Content-Type': 'text/html' });
      res.end(html);
    }
  });

  server.listen(CONFIG.port, () => {
    console.log(`🚀 Server running on http://localhost:${CONFIG.port}`);
  });

  process.on('SIGINT', () => process.exit(0));
  process.on('SIGTERM', () => process.exit(0));
}

async function getScopedToken() {
  // 1. Get all-api token. This will allow you to access the /tokeninfo
  // endpoint, which contains the information required to generate a scoped token
  const {
    data: { access_token: oidcToken },
  } = await httpRequest(`${CONFIG.instanceUrl}/oidc/v1/token?o=${CONFIG.workspaceId}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${basicAuth}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      scope: 'all-apis',
    }),
  });

  // 2. Get token info. This information is **required** for generating a token that is correctly downscoped.
  // A correctly downscoped token will only have access to a handful of APIs, and within those APIs, only
  // a the specific resources required to render the dashboard.
  //
  // This is essential to prevent leaking a privileged token.
  //
  // At the time of writing, OAuth tokens in Databricks are valid for 1 hour.
  const tokenInfoUrl = new URL(
    `${CONFIG.instanceUrl}/api/2.0/lakeview/dashboards/${CONFIG.dashboardId}/published/tokeninfo?o=${CONFIG.workspaceId}`,
  );
  tokenInfoUrl.searchParams.set('external_viewer_id', CONFIG.externalViewerId);
  tokenInfoUrl.searchParams.set('external_value', CONFIG.externalValue);

  const { data: tokenInfo } = await httpRequest(tokenInfoUrl.toString(), {
    headers: { Authorization: `Bearer ${oidcToken}` },
  });

  // 3. Generate scoped token. This call is very similar to what was issued before, but now we are providing the scoping to make the generated token
  // safe to pass to a browser.
  const { authorization_details, ...params } = tokenInfo;
  const {
    data: { access_token },
  } = await httpRequest(`${CONFIG.instanceUrl}/oidc/v1/token?o=${CONFIG.workspaceId}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${basicAuth}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      ...params,
      authorization_details: JSON.stringify(authorization_details),
    }),
  });

  return access_token;
}

startServer();

// ------------------------------------------------------------------------------------------------
// Helper functions
// ------------------------------------------------------------------------------------------------

/**
 * Helper function to create HTTP requests.
 * @param {string} url - The URL to make the request to.
 * @param {Object} options - The options for the request.
 * @param {string} options.method - The HTTP method to use.
 * @param {Object} options.headers - The headers to include in the request.
 * @param {Object} options.body - The body to include in the request.
 * @returns {Promise<Object>} A promise that resolves to the response data.
 */
function httpRequest(url, { method = 'GET', headers = {}, body } = {}) {
  return new Promise((resolve, reject) => {
    const isHttps = url.startsWith('https://');
    const lib = isHttps ? https : http;
    const options = new URL(url);
    options.method = method;
    options.headers = headers;

    const req = lib.request(options, (res) => {
      let data = '';
      res.on('data', (chunk) => (data += chunk));
      res.on('end', () => {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          try {
            resolve({ data: JSON.parse(data) });
          } catch {
            resolve({ data });
          }
        } else {
          reject(new Error(`HTTP ${res.statusCode}: ${data}`));
        }
      });
    });

    req.on('error', reject);

    if (body) {
      if (typeof body === 'string' || Buffer.isBuffer(body)) {
        req.write(body);
      } else if (body instanceof URLSearchParams) {
        req.write(body.toString());
      } else {
        req.write(JSON.stringify(body));
      }
    }
    req.end();
  });
}

function generateHTML(token) {
  return `<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Dashboard Demo</title>
    <style>
        body { font-family: system-ui; margin: 0; padding: 20px; background: #f5f5f5; }
        .container { max-width: 1200px; margin: 0 auto; height:calc(100vh - 40px) }
    </style>
</head>
<body>
    <div id="dashboard-content" class="container"></div>
    <script type="module">
        /**
         * We recommend bundling the dependency instead of using a CDN. However, for demonstration purposes,
         * we are just using a CDN.
         * 
         * We do not recommend one CDN over another and encourage decoupling the dependency from third-party code.
         */
        import { DatabricksDashboard } from "https://cdn.jsdelivr.net/npm/@databricks/aibi-client@0.0.0-alpha.7/+esm";
    
        const dashboard = new DatabricksDashboard({
            instanceUrl: "${CONFIG.instanceUrl}",
            workspaceId: "${CONFIG.workspaceId}",
            dashboardId: "${CONFIG.dashboardId}",
            token: "${token}",
            container: document.getElementById("dashboard-content")
        });
        
        dashboard.initialize();
    </script>
</body>
</html>`;
}

Stap 5: De voorbeeldtoepassing uitvoeren

Vervang de volgende waarden en voer vervolgens het codeblok uit vanuit uw terminal. Uw waarden mogen niet tussen punthaken staan (< >):

• Gebruik de URL van de werkruimte om de volgende waarden te zoeken en te vervangen:
  • <your-instance>
  • <workspace_id>
  • <dashboard_id>
• Vervang de volgende waarden door de waarden die u hebt gemaakt bij het maken van de service-principal (stap 2):
  • <service_principal_id>
  • <service_principal_secret> (cliëntgeheim)
• Vervang de volgende waarden door id's die zijn gekoppeld aan gebruikers van de externe toepassing:
  • <some-external-viewer>
  • <some-external-value>
• Vervang </path/to/example> door het pad naar het .py of .js bestand dat u in de vorige stap hebt gemaakt. Neem de bestandsextensie op.

INSTANCE_URL='https://<your-instance>.databricks.com' \
WORKSPACE_ID='<workspace_id>' \
DASHBOARD_ID='<dashboard_id>' \
SERVICE_PRINCIPAL_ID='<service-principal-id>' \
SERVICE_PRINCIPAL_SECRET='<service-principal_secret>' \
EXTERNAL_VIEWER_ID='<some-external-viewer>' \
EXTERNAL_VALUE='<some-external-value>' \
~</path/to/example>

# Terminal will output: :rocket: Server running on http://localhost:3000

Configuratieopties

Wanneer u initialiseert DatabricksDashboard, kunt u een config object doorgeven om het uiterlijk en gedrag van het ingesloten dashboard aan te passen. Het config object vereist dat een version veld ingesteld is op 1.

Het Databricks-logo verbergen

Ingesloten dashboards geven standaard een Powered by Databricks-logo weer in de voettekst. Om het logo te verbergen, stel hideDatabricksLogo: true in binnen het config object.

const dashboard = new DatabricksDashboard({
  instanceUrl: '<your-instance>.databricks.com',
  workspaceId: '<workspace_id>',
  dashboardId: '<dashboard_id>',
  token: '<scoped-token>',
  container: document.getElementById('dashboard-content'),
  config: {
    version: 1,
    hideDatabricksLogo: true,
  },
});
dashboard.initialize();

Bedien het globale filterpaneel

Standaard gebruikt een embedded dashboard zijn eigen configuratie om te bepalen of het globale filterpaneel begint uitgeklapt of ingeklapt. Om dit vanuit je applicatie te besturen, stel globalFilterVisibility in het config-object in op een van de volgende waarden:

• shownByDefault: Het paneel begint uitgeklapt. Kijkers kunnen het nog steeds inklappen.
• hiddenByDefault: Het paneel start ingeklapt. Kijkers kunnen het nog steeds openen.
• disabled: Het paneel en de schakelknop zijn volledig verborgen. Kijkers kunnen de globale filters niet openen of wijzigen.

Als je globalFilterVisibility weglaat, geldt het standaardgedrag van het dashboard.

De waarden shownByDefault en hiddenByDefault stellen alleen de begintoestand in. Kijkers kunnen het paneel daarna tonen of verbergen, en hun opgeslagen voorkeur krijgt voorrang bij latere bezoeken.

Wanneer ingesteld op disabled, zijn alleen de filterbesturingen verborgen. Filterwaarden van de embed-URL of de door de auteur geconfigureerde standaardinstellingen van het dashboard blijven van toepassing zijn en blijven de data filteren.

const dashboard = new DatabricksDashboard({
  instanceUrl: '<your-instance>.databricks.com',
  workspaceId: '<workspace_id>',
  dashboardId: '<dashboard_id>',
  token: '<scoped-token>',
  container: document.getElementById('dashboard-content'),
  config: {
    version: 1,
    globalFilterVisibility: 'shownByDefault',
  },
});
dashboard.initialize();

Gegevensdownloads in externe embed-mogelijkheden

Standaard kunnen kijkers van ingesloten dashboards gegevens downloaden als CSV-, TSV- of Excel-bestanden en visualisaties downloaden als PNG-bestanden. Als u gegevensdownloads in uw werkruimte wilt uitschakelen, kan een werkruimtebeheerder de downloadinstelling uitschakelen in de beheerconsole van de werkruimte.

Beheer dashboardfilters programmatisch

Bij externe embedding kun je de filterwaarden van een dashboard uit je applicatiecode lezen en wijzigen. Het DatabricksDashboard object biedt methoden om de huidige filterstatus te lezen, nieuwe waarden in te stellen en zich te abonneren op filterwijzigingen. Gebruik deze methoden om embedded filters te synchroniseren met je eigen bedieningselementen, filters in te stellen vanuit applicatiestatus, of je interface bij te werken wanneer een viewer een filter verandert.

De filtermethoden zijn beschikbaar nadat de bedieningselementen van het ingesloten dashboard klaar zijn. Databricks slaat aanroepen die vóór dat moment zijn gedaan tijdelijk op en voert deze uit zodra de bedieningselementen beschikbaar zijn.

Identificeer een filter

Elk filter heeft een id in de vorm <pageId>~<widgetId> die ongewijzigd blijft bij wijzigingen aan het dashboard. Om de ID’s van een dashboard te vinden, roep getFilters aan en zoek vervolgens de overeenkomst met de displayName van elk filter. Gebruik de id als de duurzame identificatie in je code, omdat displayName door de auteur wordt beheerd en kan veranderen of worden herhaald.

Een dashboard-auteur kan de ID van een filter wijzigen in de dashboardeditor door de widget of pagina te selecteren en de actie URL Updaten te gebruiken.

Filter status lezen

Bel getFilters om de huidige status van elk filter in het dashboard te lezen. Het geeft een array van filtertoestanden terug, elk met de volgende velden:

const filters = await dashboard.getFilters();
const filtersById = Object.fromEntries(filters.map((f) => [f.id, f]));
const regionFilter = filtersById['sales~region'];

Stel filterwaarden in

Roep setFilters aan met een array van filterwaarden om toe te passen. Elke waarde richt zich op een filter met zijn id en komt overeen met het type filter.

await dashboard.setFilters([{ id: 'sales~region', type: 'single-select', value: 'US' }]);

De waardevelden hangen af van het filtertype:

Om een filter te resetten of te wissen, gebruik je een van de volgende ingebouwde toestanden in plaats van een waarde:

• Standaard: { default: true } zet het filter terug naar de door de auteur geconfigureerde standaard. Een lege string of lege array doet hetzelfde.
• Alles: { all: true } selecteert elke waarde. Op een range of date-range eindpunt maakt het dat uiteinde onbegrensd, dus min: { all: true }, max: 10 betekent "minder dan of gelijk aan 10".
• Geen: { none: true } filtert alles weg. Beschikbaar op de filters single-select en multi-select.

Voor dashboards in apply-modus, waar selecties worden bewaard totdat de gebruiker op Apply klikt, past setFilters waarden standaard onmiddellijk toe. Om waarden in plaats daarvan eerst in de staging area te plaatsen, geef je { apply: false } op en commit je ze later met applyStagedFilters of verwerp je ze met cancelStagedFilters.

await dashboard.setFilters([{ id: 'sales~region', type: 'single-select', value: 'US' }], {
  apply: false,
});
await dashboard.applyStagedFilters();

Reageer op filterwijzigingen

Roep onFiltersChanged aan om een callback uit te voeren telkens wanneer de waarde van een filter verandert, hetzij door interactie met de kijker, een toegepaste setFilters aanroep of een URL-herstel. De callback ontvangt een momentopname van de huidige status van elk filter. Het wordt niet geactiveerd wanneer je je abonneert, dus lees de initiële status met getFilters. onFiltersChanged geeft een functie terug die het abonnement verwijdert.

const unsubscribe = dashboard.onFiltersChanged((filters) => {
  console.log('filters changed', filters);
});
// Later, to stop listening:
unsubscribe();

Om code uit te voeren nadat de filteropties voor het eerst beschikbaar komen, roep onFiltersReady aan. Het wordt één keer geactiveerd met de initiële filtersnapshot en geeft een functie terug die het abonnement verwijdert.