Porte I/O del Service

Le Porte I/O rappresentano le interfacce di ingresso e di uscita del Service e ne permettono l'interazione con altri Asset ALIDA (Dataset, altri Service, Model) all'interno di un Workflow.

Esse possono essere dei seguenti tipi:

• 🟢 Tondo verde: Dataset ALIDA
• 🔵 Tondo blu: Modelli di Machine Learning / matematici
• 🟩 Rettangolo verde: Generic I/O (data intermedi)
• 🟪 Quadrato viola: Flusso dati streaming
• (Invisibile): Endpoint REST API

Come visto durante il tutorial sulla creazione di un Service, per definire una Porta I/O per un Service occorrerà:

1. Creare una serie di argomenti linea di comando a livello di programma nucleo.
2. Creare delle Service Property per ogni Porta di I/O e/o Parametro di configurazione.

In questo capitolo ci occuperemo del primo punto, ossia vedremo quali argomenti linea di comando occorre gestire dal programma nucleo. Per il secondo punto si rimanda al capitolo Registrazione Service

Porte di Input

Per le Porte di Input, il programma nucleo dovrà gestire una serie di argomenti dipendenti da:

• Tipo porta
• Tipo Datasource

Nota

In fase di esecuzione, ALIDA passerà al Service una serie di argomenti linea di comando valorizzati. Assicurarsi che il programma nucleo ignori quelli che non si vogliono gestire.

Per esempio in Python ciò è realizzabile con l'uso di parse_known_args() di argparse.

Per ciascun tipo di porta daremo adesso una definizione e forniremo ulteriori dettagli circa i corrispondenti argomenti per il programma nucleo, raggruppandoli in due categorie:

• Argomenti base: determinano il tipo di porta. Per esse, l'utente deve definire le rispettive Service Properties in fase di registrazione del Service.
• Argomenti specifici della Datasource: vengono generati, valorizzati e passati automaticamente da ALIDA al programma nucleo in funzione di:
  1. Argomenti base
  2. Datasource

Tipo Dataset

Simbolo	Definizione	Esempi
	Accede ad una posizione all'interno di una delle Datasource batch definite in ALIDA. Le Datasource Batch sono: - Object Store - Tabular - Filesystem	Esempio 1 Esempio 3 Esempio 4

Argomenti base

--input-dataset

Verrà valorizzato con il percorso alla cartella contenente il Dataset (senza '/' finale) Occorre tener conto in fase di scrittura del programma nucleo, che tale cartella potrà contenere in generale uno o più file.

--input-columns (speciale | opzionale)

Questo parametro è utile qualora si trattino Dataset di tipo tabellare. Nel momento in cui esso viene specificato, ALIDA provvederà a:

1. Mostrare lato UI, al click sulla porta, una checkbox per ogni colonna della tabella.

   ^{Workflow Designer - dettagli porta di input}

2. Passare al programma nucleo, separati da virgola, i nomi delle colonne selezionate da UI come valore dell'argomento --input-columns oppure come * per indicare l'intero dataset

   Es. --input-columns=sepal_length,sepal_width,petal_length,petal_width,variety

A quel punto l'utente avrà modo di utilizzare tale elenco per implementare la riduzione delle colonne del Dataset lato programma nucleo.

Argomenti specifici della Datasource

Un sotto-insieme di argomenti passati automaticamente da ALIDA al programma nucleo contiene quelli specifici della Datasource

Nel caso di Datasource di tipo Object Storage, verranno passati i seguenti argomenti linea di comando:

Argomento	Valore
--input-dataset.storage_type	minio	(fisso)
--input-dataset.use_ssl	False o True	(in base al valore default inserito dall'utente per "Secure" in fase di definizione della Datasource)
--input-dataset.direction	input	(fisso)
--input-dataset.id	id of dataset as in the ALIDA catalogue
--input-dataset.minio_bucket	nome del bucket
--input-dataset.minIO_URL	URL dell'object store
--input-dataset.minIO_ACCESS_KEY	access key per l'object store
--input-dataset.minIO_SECRET_KEY	secret key per l'object store

---

Tipo Model

Simbolo	Definizione	Esempi
	Accede alla posizione di una Datasource contenente contenente un modello	Esempio 3 Esempio 4 Esempio 5

Argomenti base

Argomento	Valore
--input-model	percorso alla cartella contenente il modello

Argomenti specifici della Datasource

Come in porta di tipo Dataset. Con la differenza che --input-dataset diventa --input-model

Esempio:

Argomento	Valore
--input-model.storage_type	minio	(fisso)
--input-model.use_ssl	False o True	(in base a valore default o inserito dall'utente)
--input-model.direction	input	(fisso)
--input-model.id	id of dataset as in the ALIDA catalogue
--input-model.minio_bucket	nome del bucket
--input-model.minIO_URL	URL dell'object store
--input-model.minIO_ACCESS_KEY	access key per l'object store
--input-model.minIO_SECRET_KEY	secret key per l'object store

Tipo Generic I/O (per dati intermedi)

Simbolo	Definizione	Esempi
	Accede ad un volume temporaneo gestito internamente da ALIDA e svincolato dalle Datasource a catalogo	Esempio 8

Argomenti base

Ad esclusione di quelli per gli Workflow Media, non sono richiesti altri argomenti.

Occorrerà invece definire un'opportuna Service Property (vedi Registrazione Service) e quel punto il programma nucleo troverà, sul filesystem del container Docker che lo incapsula, una cartella per scrivere o per leggere dati.

Argomenti specifici della Datasource

Vedi Argomenti base sopra

Tipo Streaming

Simbolo	Definizione	Esempi
	Accede ad un topic di una Datasource di tipo Message Broker (es. Kafka)	Esempio 2 Esempio 5

Argomenti base

Argomento	Valore
--input-dataset	nome del topic

Argomenti specifici della Datasource

Argomento	Valore
--input-dataset.kafka_brokers	elenco degli URL dei broker (es. di un cluster Kafka)

Tipo REST API

La porta di tipo REST API permette di rendere un endpoint REST esposto dal Service raggiungibile da browser attraverso un apposito URL.

Non ci sono argomenti specifici per il programma nucleo. Sarà sufficiente definire una Service Properties come indicato in Registrazione Service - Porta REST API.

Una volta registrata la Service Property, lato Workflow Designer e cliccando sul Service, si avrà la possibilità di copiare l'URL dell'endpoint cliccando sull'apposito URL all'interno del pannello laterale destro. Visitanto tale pagina con un browser, l'utente avrà accessso alla risposta restituita dal Service.

^{Pannello dettaglio Service che espone porte}

Potranno raggiungere l'endpoint gli utenti autenticati e aventi i permessi necessari per l'accesso al Workflow contenente il Service.

E' possibile anche accedere all'endpoint programmaticamente utilizzando le API Key

Porte di Output

Le stesse convenzioni descritte per le porte di input si applicano a quelle di output

Per porte dataset, modello e streaming, --input diventa --output. Quindi:

• --output-dataset, --output-model

Porte Multiple

E' possibile anche specificare più porte di ingresso o di uscita. Per esempio, per definire N porte di input di tipo dataset, definire gli argomenti:

--input-dataset-<X> con X da 1 a N incrementale.

Esempio

Per definire tre porte, occorrerà definire i seguenti argomenti:

• --input-dataset-1 --input-dataset-2 --input-dataset-3

Nel caso in cui il dataset sia tabellare, allora aggiungere anche i corrispondenti --input-columns

• --input-columns-1 --input-columns-2 --input-columns-3

Nota

Ciascun --input-columns-<X> corrisponde a --input-columns-<X>per lo specifico valore di X

In modo analogo, è possibile specificare argomenti per più porte di altre tipologie:

Tipo Porta	Nome argomento	Note	Effetto sul Service
Dataset	--input-dataset-1 --input-dataset-2	Specificare anche: --input-columns-1 --input-columns-2
Modello	--input-model-1 --input-model-2	N/D
Generic I/0	INPUT GENERIC I/O	N/D
Streaming	N/D	Avere più porte di input streaming non è supportato	N/D
REST API	Prossimamente ...	Prossimamente ...	Prossimamente ...

Porte Miste

E' possibile anche miscelare porte di tipo, con cardinalità diversa

Porte	Effetto sul Service
--input-dataset-1 --input-dataset-2 --input-columns-1 --input-columns-2 --input-model

Parametri di esecuzione configurabili dall'utente

Per definire i parametri ausiliari per il Service, occorre aggiungere il corrispondente argomento linea di comando al programma nucleo.

Sono validi i nomi che non utilizzano i prefissi riservati:

• --input-dataset
• --input-columns
• --input-model

Esempio

Sono validi nomi del tipo --n_clusters, --threshold, --n_rounds, etc ...