Tutorial: Aggiunta di una funzione personalizzata

Informazioni su questa attività

In questo tutorial si sta scrivendo una funzione personalizzata, MultiplyByFactor, che multiplica una voce di input per un valore di fattore. Come parte del codice della funzione, definire come vengono rappresentati i controlli per gli elementi di ingresso e di uscita. Successivamente, specificare l'elemento di input e il valore del fattore.

Utilizzare il metodo execute_local_test per testare la funzione. Questo metodo si usa per testare qualsiasi funzione derivata da classi base in IoT Functions. Il metodo genera dati di esempio per una funzione localmente. Scrive i risultati ad un file denominato df_test_entitity_for_function_name nella directory di lavoro. Se la funzione funziona, registrarla con.

Infine, creare un tipo di dispositivo robot di esempio e applicare la nuova funzione MultiplyByFactor al tipo di dispositivo.

Questa guida utilizza l'IDE Pycharm per creare il pacchetto Python per la funzione personalizzata. Se si usa un altro IDE o, assicurarsi di usare Python 3.9.x con esso.

In alternativa, separata da questa esercitazione, è disponibile un pacchetto starter di funzioni personalizzate nelle funzioni IoT per aiutarti a iniziare a creare le tue proprie funzioni personalizzate.

Prima di iniziare

È possibile clonare un pacchetto starter e utilizzarlo come pacchetto di esempio nel proprio ambiente locale. La clonazione di un pacchetto starter ti fornisce un modo semplice per installare i pacchetti richiesti, incluse le funzioni IoT , per la tua funzione personalizzata. Il pacchetto starter fornisce un esempio della struttura di directory richiesta per il tuo pacchetto personalizzato.

1. Installa Python 3.9.x nel tuo ambiente.
2. Installare GIT.
3. Installare il gestore pacchetti pip3 per Python.
4. Installare un editor, come ad esempio Xcode, per effettuare aggiornamenti del codice.
5. Clona il pacchetto starter HelloWorld
   1. Aprire una finestra di terminale
   2. Fare una nuova cartella di progetto per il pacchetto starter. Ad esempio, mkdir project.
   3. Passare alla directory del progetto. Ad esempio, cd project.
   4. Clonare il pacchetto starter. Immettere: git clone --branch starter_package https://github.com/ibm-watson-iot/functions.git
   5. Verificare di aver clonato il pacchetto starter alla directory del progetto.
   6. Passare alla directory delle funzioni nel pacchetto starter. Immettere: cd functions
   7. Immettere: git status
   8. Copiare il percorso della directory di lavoro per un utilizzo successivo. Inserire pwd e copiare il percorso.
   9. Aprire il file setup.py. Il file setup.py definisce il nome del pacchetto e l'elenco dei pacchetti richiesti per il progetto.
   10. Impostare il parametro name su custom{your_initials}. Sostituire la variabile {your_initials} con le tue iniziali o con un altro valore univoco.
   11. Nel repository ibm-watson-iot/functions , verificare che il pacchetto iotfunction sia la versione corretta. Ad esempio, per 8.8, il pacchetto deve appartenere al ramo 8.8.X GitHub. Non sostituire x nella versione con un altro valore. Il testo seguente è un esempio di file setup.py . Il parametro nome è impostato su customId e viene utilizzato il ramo 8.7.X .

#!/usr/bin/env python 
from setuptools import setup, find_packages
setup(name='customld', version='0.0.1', packages=find_packages(),
install_requires=['iotfunctions@git+https://github.com/ibm-watson-iot/functions.git@8.7.x'])

1. Installare l'edizione della comunità PyCharm .
2. In PyCharm, puntare l'ambiente al pacchetto iniziale clonato. Clicca su Apri e sfoglia per trovare la directory clonata.
3. Impostare un nuovo ambiente virtuale Pycharm.
   1. Andare a PyCharm > Preferenze> Project < your_project>> Project Interpreter.
   2. Se si sta impostando un nuovo ambiente virtuale:
   3. Fare clic sull'icona delle impostazioni e fare clic su Aggiungi.
   4. Specificare la posizione della cartella del progetto.
   5. Imposta l'interprete di base nella directory Python 3.9.x .
   6. Se si dispone di un ambiente virtuale esistente, impostare l'interprete del progetto in Python 3.x.
4. Eseguire il seguente comando per installare il pacchetto iotfunctions nel tuo ambiente Python . Assicurarsi di utilizzare il nome filiale corretto per la propria versione.

       pip3 install git+https://github.com/ibm-watson-iot/functions.git@8.7.x --upgrade

Assicuratevi di utilizzare sempre la versione più recente di IoT Functions. Verificare la versione di ciascun modulo Python supportato da. Se non si utilizza la versione esatta supportata, la pipeline potrebbe romperlo.

Passi

Completa questi passaggi per applicare un calcolo ai dati di esempio utilizzando una funzione personalizzata.

Passo 1: Definire il calcolo

Un'azienda che sviluppa braccia robotiche sta introducendo un nuovo braccio robotico e sta testando che esso esegue oltre che la robotica esistente. Nei primi test la squadra ha scoperto che per alcuni dei robot la distanza percorsa durante i test era troppo alta. Dopo le indagini, il team ha scoperto che gli strumenti utilizzati per fare i test stavano aggiungendo un ritardo alla velocità e ai tempi di viaggio del robot. Il gestore delle operazioni vuole regolare entrambi i valori per un fattore di 2 ma vuole che la flessibilità cambi quel valore in seguito.

L'analista identifica che un calcolo simile potrebbe essere utile in altri calcoli e generalizza la funzione scrivendo una classe MultiplyByFactor .

distance * factor

Passo 2: impacchetta la tua funzione e memorizzarla in GitHub.

1. Crea un nuovo repository su GitHub per il pacchetto starter che hai clonato.
   1. Il repository deve avere un file di configurazione ( URL ) accessibile da un pip install.
   2. Una best practice è quella di rendere il repository privato. È possibile accedere al repository utilizzando un token di accesso personale.
2. Aggiungere un file al repository per creare il ramo master. Ad esempio, aggiungere un file vuoto che si chiama test.md e fare clic su Commit new file.
3. Apri il progetto in PyCharm localmente per la modifica.
4. Verificare che il progetto abbia la seguente struttura di directory e file:

   functions
   |
   |__ setup.py
   |
   |__ scripts
     |
     |_ local_test_of_function.py
   |
   |__ custom
     |
     |_ functions.py
     |_  __init__.py

5. Modificare il nome del modulo, custom, ad un nome univoco, come customyourinitials. Ad esempio, customld.
6. Creare un modulo funzione multiplybyfactor<yourinitials>.py in custom<yourinitials> e incollare il seguente codice. Aggiornare le variabili in <> per abbinare il proprio ambiente. Ad esempio, se il codice è in GitHub, si può impostare 'PACKAGE_URL su ''git+https://<XXXXXX>@github.com/github.com/jones/starter@starter_package'.

   In questa funzione, si implementano due metodi. Aggiungete il calcolo al metodo execute . Si impostano gli input e gli output degli argomenti per la funzione nel metodo build_ui . Questi argomenti sono configurati tramite l'interfaccia utente di configurazione.

   import inspect
   import logging
   import datetime as dt
   import math
   from sqlalchemy.sql.sqltypes import TIMESTAMP,VARCHAR
   import numpy as np
   import pandas as pd
   
   from iotfunctions.base import BaseTransformer
   from iotfunctions import ui
   
   logger = logging.getLogger(__name__)
   
   # Specify the URL to your package here.
   # This URL must be accessible via pip install.
   # Example assumes the repository is private.
   # Replace XXXXXX with your personal access token.
   # After @ you must specify a branch.
   
   PACKAGE_URL = 'git+https://XXXXXX@github.com/<user_id><path_to_repository>@starter_package'
   
   class MultiplyByFactor<YourInitials>(BaseTransformer):
   
       def __init__(self, input_items, factor, output_items):
   
           self.input_items = input_items
           self.output_items = output_items
           self.factor = float(factor)
           super().__init__()
       def execute(self, df):
           df = df.copy()
           for i,input_item in enumerate(self.input_items):
               df[self.output_items[i]] = df[input_item] * self.factor
           return df
   
       @classmethod
       def build_ui(cls):
           #define arguments that behave as function inputs
           inputs = []
           inputs.append(ui.UIMultiItem(
                   name = 'input_items',
                   datatype=float,
                   description = "Data items adjust",
                   output_item = 'output_items',
                   is_output_datatype_derived = True)
                         )        
           inputs.append(ui.UISingle(
                   name = 'factor',
                   datatype=float)
                         )
           outputs = []
           return (inputs,outputs)   

Passo 3: Salvare le credenziali in un file

Impostare le credenziali per la connessione a.

1. Scarica il file credentials_as.json.
2. Sostituire le variabili con i dati e salvare il file sulla macchina locale.

Il file delle credenziali viene utilizzato per eseguire o testare la funzione localmente. Non spingere questo file sul proprio repository esterno in passo 4.

Passo 4: invia le tue modifiche locali al tuo repository GitHub

Verificare di aver completato questi passaggi:

• I file che hai modificato puntano ancora al repository GitHub da cui hai clonato il codice. Modifica il repository remoto nel tuo repository GitHub .
• Verificare che il file delle credenziali non sia incluso con il codice funzione prima dell'impegno delle modifiche alla propria directory esterna.

Esegui il push del codice funzione al tuo repository esterno in GitHub.

1. Aprire una finestra terminale nella cartella del progetto.
2. Inserire: git remote -v. Il repository remoto punta ancora su https://github.com/ibm-watson-iot/functions
3. Modificare l' URL e di origine remota utilizzando i seguenti comandi:

   git remote set-url origin URL_To_YOUR_GITHUB_REPOSITORY

   Confermare che gli URL di Fetch e Push puntano sul tuo repository.
4. Aggiungere il remoto a monte utilizzando il seguente comando. Immettere:

   git remote add upstream https://github.com/ibm-watson-iot/functions.git

5. Aggiungere i tuoi file a GIT e impegnarli.
   1. In PyCharm, selezionare la cartella 'custom<your_initials>.
   2. Selezionare Git > Aggiungi.
   3. Selezionare Git > Commit.
   4. Nella finestra Commit delle modifiche, fare clic su Commit.
   5. Selezionare Git > Repository> Push.
   6. Fare clic su Push.
6. Verifica che il tuo modulo sia stato spinto a un ramo starter_package nel tuo repository.

Passo 5: Installare la funzione personalizzata nel proprio ambiente locale

Installare la funzione personalizzata nel proprio ambiente locale. Aggiornare le variabili in <> per abbinare il proprio ambiente.

pip3 install git+https://<XXXXXX>@github.com/<user_id><path_to_repository>@starter_package --upgrade

Ad esempio:

pip3 install git+https://<XXXXXX>@github.com/jones/starter@starter_package --upgrade

Sostituire < xxxxxx> con il tuo token di accesso personale. < /xxxxxx>

Passo 6: Test la tua funzione personalizzata localmente.

1. Creare uno script chiamato test_my_custom_function.py nella cartella scripts . Nello script, importare le librerie e i pacchetti Python :

   import datetime as dt
   import json
   import pandas as pd
   import numpy as np
   from sqlalchemy import Column, Integer, String, Float, DateTime, Boolean, func
   from iotfunctions.base import BaseTransformer
   from iotfunctions.metadata import EntityType
   from iotfunctions.db import Database
   from iotfunctions import ui

2. Collegarsi a. Nello script test_my_custom_function.py , aggiungere:

   with open('credentials_as.json', encoding='utf-8') as F:
     credentials = json.loads(F.read())
   db_schema = None
   db = Database(credentials=credentials)

3. Importare e instanziare la funzione. Nello script test_my_custom_function.py , aggiungere il seguente codice. Aggiornare le variabili in <> per abbinare il proprio ambiente.

   from custom<yourinitials>.multiplybyfactor<yourinitials> import MultiplyByFactor<YourInitials>
   fn = MultiplyByFactor<YourInitials>(
       input_items = ['speed', 'travel_time'],
       factor = '2',
       output_items = ['adjusted_speed', 'adjusted_travel_time']
                 )
   df = fn.execute_local_test(db=db, db_schema=db_schema, generate_days=1,to_csv=True)
   print(df)

4. Eseguire lo script dalla riga di comando. I risultati dell'intervallo di date vengono salvati in un file .csv . Cercare df_test_entity_for_multiplybyfactor<your_initials>.csv nella directory scripts. Immettere:

   python3 test_my_custom_function.py

Passo 7: Registrare la tua funzione personalizzata.

1. Creare uno script chiamato register_my_custom_function.py nella cartella scripts . Nello script, importare le librerie e i pacchetti Python :

   import datetime as dt
   import json
   import pandas as pd
   import numpy as np
   from sqlalchemy import Column, Integer, String, Float, DateTime, Boolean, func
   from iotfunctions.base import BaseTransformer
   from iotfunctions.metadata import EntityType
   from iotfunctions.db import Database
   from iotfunctions import ui

2. Collegarsi a. Nello script register_my_custom_function.py , aggiungere:

   with open('credentials_as.json', encoding='utf-8') as F:
     credentials = json.loads(F.read())
   db_schema = None
   db = Database(credentials=credentials)
   ``

3. Nello script register_my_custom_function.py , per registrare la funzione, aggiungere il seguente codice. Aggiornare le variabili in <> per abbinare il proprio ambiente.

   from custom<yourinitials>.multiplybyfactor<yourinitials> import MultiplyByFactor<YourInitials>
   
   db.register_functions([MultiplyByFactor<YourInitials>])

4. Eseguire lo script dalla riga di comando. Ad esempio:

   python3 register_my_custom_function.py

Passo 8: Creare un tipo di dispositivo di esempio.

1. Nella pagina di impostazione, nella scheda Tipi di dispositivo, fare clic su Aggiungi tipo di dispositivo + per aggiungere un nuovo tipo di dispositivo.
2. Selezionare il modello del tipo di campione Robot industriale.
3. Assegnare un nome al tipo di dispositivo nel campo Nome del tipo di dispositivo.
4. Fare clic su Crea.
5. Selezionare il tipo di dispositivo campione appena creato da Tipi di dispositivi, fare clic sul pulsante con le ellissi (3 punti disposti verticalmente) e selezionare Modifica, per aprire la scheda Dati del tipo di dispositivo campione.

La generazione delle metriche richiede fino a 5 minuti.

Passo 9: Applicare la funzione personalizzata al tipo di dispositivo.

1. Se non è stata creata una metrica distance , aggiungelo. Seguire la procedura descritta in Esercitazione: Aggiunta di espressioni
2. Dalla scheda Dati , fare clic su Crea metrica.
3. Selezionare la funzione MultiplyByFactor<YourInitials> dal catalogo.
4. Impostare l'ambito e quindi fare clic su Avanti.
5. Nel campo del fattore, inserire 2.
6. Nel campo input_item , selezionare distance.
7. Fare clic su Avanti.
8. Rinominare l'output in 'adjusted_distance'.
9. Fare clic su Crea.
10. Nella lista degli articoli di dati, selezionare adjusted_distance. Attendere fino a 5 minuti per valutare la funzione personalizzata rispetto ai dati del campione.