Costruisci un connettore personalizzato per Lakeflow Connect

I connettori personalizzati permettono di assorbire dati da una fonte che Lakeflow Connect non supporta con un connettore gestito. Costruisci e testi il tuo connettore, poi lo distribuisci ed esegui nel tuo workspace Azure Databricks. Non è necessario registrarlo presso la community o contribuire a un repository condiviso per poterlo usare.

Sviluppa il tuo connettore utilizzando gli strumenti e i template presenti nel repository Lakeflow Community Connectors su GitHub. Il repository include strumenti di sviluppo basati sull'intelligenza artificiale per facilitare ogni fase, tra cui ricerca di origine, configurazione dell'autenticazione, implementazione e test.

Se in seguito vorrai condividere il tuo connettore con altri utenti, potrai contribuire alla comunità. Per utilizzare un connettore comunitario esistente, vedi Connettori comunitari in Lakeflow Connect.

Requisiti

Prima di iniziare, assicurarsi di avere:

• Python 3.10 o versione successiva
• Un'area di lavoro Azure Databricks con il catalogo Unity abilitato
• Credenziali API per l'origine a cui ci si vuole connettere
• Git installato in locale

Configurare il repository

Clonare il repository Lakeflow Community Connectors e installare le dipendenze di sviluppo.

1. Clonare il repository:

   git clone https://github.com/databrickslabs/lakeflow-community-connectors.git
   cd lakeflow-community-connectors
   

2. Creare un ambiente virtuale e installare le dipendenze:

   python -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   

3. Esaminate le implementazioni dei connettori esistenti in src/databricks/labs/community_connector/sources/, quindi iniziate a sviluppare il connettore in una nuova directory all'interno di quel percorso. Seguire i comandi e le funzionalità di sviluppo assistito da IA del repository. Per il flusso di lavoro consigliato, usare:

   /develop-connector <your-source>
   /validate-connector <your-source>
   

Implementare l'interfaccia LakeflowConnect

Ogni connettore implementa l'interfaccia LakeflowConnect , che definisce come il tuo connettore si autentica, scopre tabelle, restituisce gli schemi e legge i dati.

class LakeflowConnect:
    def __init__(self, options: dict[str, str]) -> None:
        """Initialize with connection parameters"""

    def list_tables(self) -> list[str]:
        """Return names of all tables supported by this connector."""

    def get_table_schema(self, table_name: str, table_options: dict[str, str]) -> StructType:
        """Return the Spark schema for a table."""

    def read_table_metadata(self, table_name: str, table_options: dict[str, str]) -> dict:
        """Return metadata: primary_keys, cursor_field, ingestion_type
        (snapshot|cdc|cdc_with_deletes|append)."""

    def read_table(self, table_name: str, start_offset: dict,
                   table_options: dict[str, str]) -> (Iterator[dict], dict):
        """Yield records as JSON dicts and return the next offset
        for incremental reads."""

    def read_table_deletes(self, table_name: str, start_offset: dict,
                           table_options: dict[str, str]) -> (Iterator[dict], dict):
        """Optional: Only required if ingestion_type is 'cdc_with_deletes'."""

Descrizioni dei metodi

La tabella seguente descrive ogni metodo nell'interfaccia LakeflowConnect :

Sviluppare il connettore

Seguire questa procedura per compilare e convalidare un nuovo connettore:

1. Ricercare l'API di origine: studiare le specifiche dell'API di origine, i meccanismi di autenticazione, i limiti di frequenza e gli schemi di dati disponibili. Identificare le tabelle o gli endpoint da esporre.

2. Configurare l'autenticazione: generare la specifica di connessione, configurare le credenziali per l'origine e verificare la connettività dall'ambiente di sviluppo.

3. Implementare il connettore: codificare tutti i metodi di interfaccia necessari LakeflowConnect per connettersi all'API di origine e restituire i dati nel formato previsto.

4. Test e iterazione: eseguire i gruppi di test standard in un sistema di origine reale e risolvere eventuali problemi. Per informazioni dettagliate, vedere Testare il connettore .

5. Documentare il connettore: scrivere un file YAML rivolto all'utente README.md e generare il file YAML della specifica del connettore che descrive i parametri configurabili del connettore.

6. Compilare l'artefatto di distribuzione: eseguire lo script di compilazione per produrre l'artefatto a file singolo che può essere distribuito in un'area di lavoro.

Testare il connettore

Il repository offre diversi approcci di test:

Gruppo di test generico (obbligatorio)

Questa suite si collega a una fonte reale utilizzando le credenziali fornite per verificare la funzionalità end-to-end, inclusa autenticazione, scoperta di schema e letture dei dati.

python -m pytest tests/generic/ --connector <your-source> --credentials credentials.json

Test writeback (scelta consigliata)

Il test di write-back esegue cicli di scrittura-lettura-verifica per validare letture e cancellazioni incrementali. Ciò conferma che il rilevamento degli offset e la logica CDC funzionano correttamente.

python -m pytest tests/writeback/ --connector <your-source> --credentials credentials.json

Unit test

Scrivere test unitari per qualsiasi logica personalizzata complessa nel connettore, ad esempio la gestione della paginazione, la coercizione dei tipi o il recupero dagli errori.

Compilare l'artefatto di distribuzione

Dopo che il tuo connettore supera le suite di test, impacchettalo in modo che una pipeline possa eseguirlo. Un connettore si apre in due parti:

• Un artefatto sorgente a file singolo. Esegui lo script di merge per appiattire il connettore in un unico file Python autonomo. La pipeline usa questo file in fase di esecuzione anziché il repository completo.

  python tools/scripts/merge_python_source.py --connector <your-source>
  

  Lo script scrive questo file su dist/<your-source>/.

• Python wheels (.whl) per le dipendenze del connettore. Il framework dei connettori e tutte le librerie di terze parti importate dal tuo connettore devono essere disponibili per la pipeline come ruote memorizzate in un volume del Catalogo Unity. Se queste ruote mancano, la pipeline può guastarsi durante la scoperta della fonte. Puoi caricarli tu stesso e consultarli nell'interfaccia, oppure lasciare che la CLI del Community Connector li costruisca e carichi per te. Consulta Eseguire il deployment con Community Connector CLI.

Installa il tuo connettore in uno dei due modi:

• L'interfaccia di Azure Databricks è il percorso punta e clicca. Usalo per una distribuzione unica quando fornisci tu stesso le ruote del connettore nel campo delle dipendenze della Biblioteca . Vedi Deploy nell'interfaccia di Databricks.
• La community-connector CLI è l'opzione automatizzabile tramite script. Usalo quando sviluppi localmente e vuoi che le ruote del connettore vengano costruite e caricate per te, oppure quando vuoi un deployment ripetibile che puoi automatizzare. Consulta Eseguire il deployment con Community Connector CLI.

Distribuzione nell'interfaccia di Databricks

Distribuisci il tuo connettore nell'interfaccia di Azure Databricks in due fasi: aggiungi il connettore, poi crea la pipeline.

Aggiungi il connettore personalizzato

Prima di tutto, aggiungi il tuo connettore in modo che appaia come una casella nella pagina Aggiungi dati :

1. Nella barra laterale del tuo workspace Azure Databricks, clicca su +Aggiungi>o carica dati nuovi, poi, sotto connettori Community, aggiungi un connettore personalizzato.
2. In Nome origine immettere il nome del connettore. Questo deve corrispondere al nome della directory che contiene il codice sorgente del tuo connettore (sources/<source-name>).
3. Per il nome visualizzato, inserisci un nome amichevole per il connettore. Se lasci questo vuoto, verrà utilizzato il nome di origine come predefinito.
4. Per le dipendenze delle librerie, aggiungi i file Python wheel (.whl) di cui il connettore ha bisogno da un volume del Catalogo Unity. Vedi Creare l'artefatto di distribuzione.
5. Per la specifica di connessione, incolla la specifica di connessione del connettore in YAML, in modo che corrisponda al file connector_spec.yaml.
6. Fare clic su Salva. Il connettore appare come un riquadro personalizzato nella sezione Connettori della community.

Creare la pipeline di inserimento

Poi crea la pipeline che prende i dati dalla tua fonte:

1. Seleziona il riquadro del tuo connettore per aprire la procedura guidata Acquisisci dati.
2. Nel passaggio Connessione, clicca + Crea connessione oppure seleziona una connessione esistente, inserisci i dettagli della connessione della tua fonte, poi clicca su Avanti.
3. Nel passaggio di configurazione Ingestione , inserisci un nome Pipeline, imposta la posizione del Registro Eventi (catalogo e schema), scegli un tipo di Calcolo, poi clicca su Crea pipeline e continua.
4. Nella fase Sorgente, seleziona le tabelle da acquisire.
5. Nel passaggio Destinazione , scegli il catalogo e lo schema dove vengono scritte le tabelle ingerite.
6. Nel passaggio Programmazioni e notifiche, imposta un programma opzionale e notifiche, poi finisci.
7. Esegui la pipeline manualmente o secondo i suoi tempi.

Per configurare ulteriormente la pipeline, puoi modificare ingest.py nell'editor della pipeline. Vedi Opzioni di configurazione della pipeline.

Opzioni di configurazione della pipeline

È possibile configurare le opzioni seguenti in ingest.py:

Distribuire con la CLI del Community Connector

Il comando della publish CLI costruisce il framework e le ruote dei connettori dalla tua fonte locale, li carica su un volume del Catalogo Unity, registra i loro percorsi nel manifesto del connettore e pubblica il connettore come una tessera Personalizzata nella pagina Aggiungi dati . Puntalo verso le specifiche del connettore locale così non cercherà il connettore nel repository upstream:

community-connector publish <your-source> \
  --spec src/databricks/labs/community_connector/sources/<your-source>/connector_spec.yaml

Per riutilizzare le ruote che hai già costruito e saltare la fase di costruzione, passale con --package. Per sostituire un connettore che hai pubblicato prima, aggiungi --overwrite. Per l'elenco completo delle opzioni, inclusi --package, --volume-path, --catalog, e --schema, vedi il publish riferimento al comando.

Per eseguire l'intero flusso di lavoro dalla riga di comando, inclusa la creazione di una connessione, la creazione e l'aggiornamento della pipeline di ingestione, la pubblicazione e la dispubblicazione, consulta il riferimento alla CLI Community Connector.

Contribuisci con il tuo collegamento alla comunità

Il tuo connettore gira nel tuo spazio di lavoro, che tu lo contribuisca o meno. Se vuoi condividerlo affinché altri utenti possano scoprirlo e utilizzarlo, apri una pull request nel repository Lakeflow Community Connectors . I connettori forniti dalla community diventano connettori della community, mantenuti dalla community e non coperti dagli SLA di Databricks.