チュートリアル: カスタム関数の追加

このチュートリアルでは、パッケージ化して GitHub リポジトリーに保管するカスタム関数を作成します。 その関数を、カタログに登録して計算で使用する前に、ローカル環境でテストします。

このタスクについて

注: このチュートリアルを完了するには、サンプルのデバイス・タイプ・テンプレートとデータを使用します。 サンプル・デバイス・タイプは、最新バージョンのデバイス・タイプを使用せず、ストリーミング・データ・メトリックをサポートしません。 詳しくは、 バッチ・データ・メトリックまたはストリーミング・データ・メトリックの作成を参照してください。

このチュートリアルでは、入力項目を係数値でかけるカスタム関数 MultiplyByFactorを作成しています。 ファンクションコードの一部として、入出力項目のコントロールをどのように表現するかを定義する。 後で、入力項目と係数値を指定します。

execute_local_test メソッドを使用して、関数をテストします。 このメソッドを使用して、IoT 関数内の基本クラスから派生したすべての関数をテストします。 このメソッドは、関数のサンプル・データをローカルで生成します。 このコマンドは、作業ディレクトリー内の df_test_entitity_for_function_name という名前のファイルに結果を書き込みます。 その関数が動作したら、.NET Frameworkに登録する。

最後に、サンプルのロボット・デバイス・タイプを作成し、新しい MultiplyByFactor 関数をデバイス・タイプに適用します。

このチュートリアルでは、Pycharm IDE を使用してカスタム関数の Python パッケージを作成します。 他のIDEを使う場合は、 Python 3.9.x。

代わりに、このチュートリアルとは別に、 カスタム関数スターター・パッケージ を IoT 機能で使用することにより、独自のカスタム関数の作成を開始することができます。

始める前に

スターター・パッケージを複製し、それをローカル環境でサンプル・パッケージとして使用することができます。 スターター・パッケージを複製することで、カスタム関数用に必要なパッケージ (IoT 関数を含む) を簡単にインストールできます。 スターター・パッケージは、カスタム・パッケージに必要なディレクトリー構造の例を提供します。

  1. ご使用の環境に Python 3.9.x をインストールします。
  2. GIT をインストールします。
  3. Pythonの pip3 パッケージ・マネージャーをインストールします。
  4. コードの更新を行うには、 Xcodeなどのエディターをインストールします。
  5. HelloWorld スターター・パッケージ の複製
    1. 端末ウィンドウを開きます。
    2. スターター・パッケージ用の新規プロジェクト・フォルダーを作成します。 例えば、mkdir project などです。
    3. プロジェクト・ディレクトリーに移動します。 例えば、cd project などです。
    4. スターター・パッケージを複製します。 次のように入力します。 git clone --branch starter_package https://github.com/ibm-watson-iot/functions.git
    5. スターター・パッケージがプロジェクト・ディレクトリーに複製されたことを確認します。
    6. スターター・パッケージの functions ディレクトリーに移動します。 次のように入力します。 cd functions
    7. 次のように入力します。 git status
    8. 後で使用できるように、作業ディレクトリーのパスをコピーします。 pwd を入力してパスをコピーします。
    9. setup.py ファイルを開きます。 setup.py ファイルは、パッケージ名と、プロジェクトに必要なパッケージのリストを定義します。
    10. name パラメーターを custom{your_initials}に設定します。 {your_initials} 変数を、イニシャルまたは別の固有値に置き換えます。
    11. ibm-watson-iot/functions リポジトリーで、 iotfunction パッケージが正しいバージョンであることを確認します。 例えば、 8.8 の場合、パッケージは 8.8.X GitHub ブランチのものでなければならない。 バージョンの x を別の値で置き換えないでください。 以下の文章は、 setup.py ファイルの例である。 nameパラメータは customId 、 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. PyCharmcommunity edition をインストールします。
  2. PyCharm で、ご使用の環境が複製したスターター・パッケージを指すようにします。 開く をクリックして参照し、複製したディレクトリーを見つけます。
  3. 新しい Pycharm 仮想環境をセットアップします。
    1. PyCharm > 設定 > プロジェクト <your_project> > プロジェクト・インタープリターに移動します。
    2. 新しい仮想環境をセットアップする場合は、次のようにします。
    3. 設定アイコンをクリックして、 追加をクリックします。
    4. プロジェクト・フォルダーの場所を指定します。
    5. 基本インタープリターを Python 3.9.x ディレクトリーに設定します。
    6. 既存の仮想環境がある場合は、プロジェクト・インタープリターを Python 3.x に設定します。
  4. 以下のコマンドを実行して、 iotfunctions パッケージを Python 環境にインストールします。 ご使用のバージョンの正しいブランチ名を使用していることを確認してください。
        pip3 install git+https://github.com/ibm-watson-iot/functions.git@8.7.x --upgrade

IoT 関数は必ず最新バージョンを使用してください。 .NETがサポートしている各 Python モジュールのバージョンを確認する。 サポートされている正確なバージョンを使用しないと、パイプラインが切断される可能性があります。

ステップ

カスタム関数を使用してサンプル・データに計算を適用するには、以下のステップを実行します。

ステップ 1: 計算を定義する

ロボット・アームを開発する会社が、新しいロボット・アームを導入し、既存のロボット・アームだけでなくその機能もテストしています。 初期のテストでは、一部のロボットについて、テスト中の移動距離が高すぎることが発見されました。 調査の結果、チームは、テストに使用されたツールが原因で、ロボットの速度と移動時間に遅延が生じていることを発見しました。 運用管理者は、両方の値を 2 倍に調整したいと考えていますが、後でその値を変更できる柔軟性も確保する必要があります。

アナリストは、類似の計算が他の計算に役立つ可能性があり、 MultiplyByFactor クラスを作成することによって関数を一般化することを示しています。

distance * factor

ステップ 2: 関数をパッケージ化して GitHub に保管する

  1. 複製したスターター・パッケージ用の新規リポジトリーを GitHub に作成します。
    1. リポジトリーには、pip install からアクセスできる URL が必要です。
    2. ベスト・プラクティスとして、リポジトリーはプライベートにしてください。 リポジトリーには、個人アクセス・トークンを使用してアクセスできます。
  2. ファイルをリポジトリーに追加して、マスター・ブランチを作成します。 例えば、 test.md という名前の空のファイルを追加し、 Commit new fileをクリックします。
  3. プロジェクトを編集するために、ローカルの PyCharm 内で開きます。
  4. プロジェクトに以下のディレクトリー構造とファイルがあることを確認します。
    functions
|
|__ setup.py
|
|__ scripts
  |
  |_ local_test_of_function.py
|
|__ custom
  |
  |_ functions.py
  |_  __init__.py
  5. モジュール名 custom を、 customyourinitials などの固有の名前に変更します。 例えば、customld のようになります。
  6. custom<yourinitials>でmultiplybyfactor<yourinitials>.py関数モジュールを作成し、以下のコードを貼り付けます。 ご使用の環境に合わせて<>の変数を更新します。 例えば、コードが GitHub にある場合は、PACKAGE_URLを'git+https://<XXXXXX>@github.com/github.com/jones/starter@starter_package'に設定できます。

    この関数では、2 つのメソッドを実装します。 execute メソッドに計算を追加します。 関数の入力引数および出力引数を build_ui メソッドに設定します。 これらの引数は、構成ユーザー・インターフェースを介して構成されます。

    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)

ステップ 3: 資格情報をファイルに保存する

.NETに接続するための認証情報を設定する。

  1. credentials_as.json ファイルをダウンロードします。
  2. 変数をデータに置き換え、ファイルをローカル・マシンに保存します。

資格情報ファイルは、関数をローカルで実行またはテストするために使用されます。 このファイルを ステップ 4内の外部リポジトリーにプッシュしないでください。

ステップ 4: ローカルの変更を GitHub リポジトリーにプッシュする

以下のステップが完了していることを確認します。

  • 変更後のファイルも、引き続き、コードの複製元の GitHub リポジトリーを指しています。 リモート・リポジトリーを GitHub リポジトリーに変更してください。
  • 変更を外部ディレクトリーにコミットする前に、関数コードに資格情報ファイルが含まれていないことを確認します。

関数コードを GitHub 内の外部リポジトリーにプッシュします。

  1. プロジェクト・フォルダーで端末ウィンドウを開きます。
  2. 入力: git remote -v. リモート・リポジトリーは引き続き https://github.com/ibm-watson-iot/functions を指しています。
  3. 以下のコマンドを使用して、リモート起点 URL を変更します。
    git remote set-url origin URL_To_YOUR_GITHUB_REPOSITORY
    フェッチ URL およびプッシュ URL がご使用のリポジトリーを指していることを確認します。
  4. 以下のコマンドを使用して、アップストリーム・リモートを追加します。 次のように入力します。
    git remote add upstream https://github.com/ibm-watson-iot/functions.git
  5. ファイルを GIT に追加し、コミットします。
    1. PyCharm で、custom<your_initials>ディレクトリーを選択します。
    2. 「Git」>「Add」を選択します。
    3. 「Git」>「Commit」を選択します。
    4. 変更のコミット・ウィンドウで コミットをクリックします。
    5. 「Git」>「Repository」>「Push」を選択します。
    6. プッシュをクリックします。
  6. モジュールがリポジトリー内の starter_package ブランチにプッシュされたことを確認します。

ステップ 5: カスタム関数をローカル環境にインストールする

ローカル環境にカスタム関数をインストールします。 ご使用の環境に合わせて<>の変数を更新します。

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

以下に例を示します。

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

< xxxxxx> を個人用アクセス・トークンに置き換えます。< /xxxxxx>

ステップ 6: カスタム関数をローカルでテストする

  1. scripts フォルダーに test_my_custom_function.py というスクリプトを作成します。 このスクリプトで、以下のように 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. に接続する。 test_my_custom_function.py スクリプトで、以下を追加します。
    with open('credentials_as.json', encoding='utf-8') as F:
  credentials = json.loads(F.read())
db_schema = None
db = Database(credentials=credentials)
  3. 関数をインポートしてインスタンス化します。 test_my_custom_function.py スクリプトで、以下のコードを追加します。 ご使用の環境に合わせて<>の変数を更新します。
    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. コマンド・ラインからスクリプトを実行します。 日付フレームの結果は .csv ファイルに保存されます。 スクリプト・ディレクトリーで df_test_entity_for_multiplybyfactor<your_initials>.csv を探します。 次のように入力します。
    python3 test_my_custom_function.py

ステップ 7: カスタム関数を登録する

  1. scripts フォルダーに register_my_custom_function.py というスクリプトを作成します。 このスクリプトで、以下のように 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. に接続する。 register_my_custom_function.py スクリプトで、以下を追加します。
    with open('credentials_as.json', encoding='utf-8') as F:
  credentials = json.loads(F.read())
db_schema = None
db = Database(credentials=credentials)
``
  3. register_my_custom_function.py スクリプトで関数を登録するには、以下のコードを追加します。 ご使用の環境に合わせて<>の変数を更新します。
    from custom<yourinitials>.multiplybyfactor<yourinitials> import MultiplyByFactor<YourInitials>

db.register_functions([MultiplyByFactor<YourInitials>])
  4. コマンド・ラインからスクリプトを実行します。 以下に例を示します。
    python3 register_my_custom_function.py

ステップ 8: サンプル・デバイス・タイプの作成

注記： サンプル・デバイス・タイプの作成手順は、 Maximo Manage 9.0 以降のバージョンにのみ適用されます。 Maximo Manage 8.9 以前のバージョンでは、Setup ページの Devices タブに進み、プラス（＋）アイコンをクリックして Robot sample type テンプレートを選択してください。
  1. Setup（セットアップ） ページの Device types（デバイス・タイプ ）タブで、Add device type +（デバイス・タイプの追加）をクリックし、新しいデバイス・タイプを追加します。
  2. 産業用ロボットのサンプルタイプのテンプレートを選択します。
  3. Device type name（デバイスタイプ名）フィールドでデバイスタイプに名前を付けます。
  4. 作成をクリックします。
  5. Device types（デバイスタイプ ）から新しく作成したサンプルデバイスタイプを選択し、楕円ボタン（縦に並んだ3つの点）をクリックして Edit（編集 ）を選択すると、サンプルデバイスタイプの Data（データ） タブが開きます。

メトリックの生成には最大 5 分かかります。

ステップ 9: カスタム関数をデバイス・タイプに適用します。

  1. distance メトリックを作成していない場合は、追加します。 チュートリアル: 式の追加のステップに従ってください。
  2. 「データ」 タブで、 「メトリックの作成」をクリックします。
  3. カタログからMultiplyByFactor<YourInitials>関数を選択します。
  4. スコープを設定し、 「次へ」をクリックします。
  5. 「係数」フィールドに 2 を入力します。
  6. input_item フィールドで、 distanceを選択します。
  7. 次へをクリックします。
  8. 出力の名前を「adjusted_distance」に変更します。
  9. 作成をクリックします。
  10. データ項目リストで、adjusted_distanceを選択します。 サンプルデータに対してカスタム関数を評価するため、最大5分間待ちます。