UiPath Studioで使える！Data Service操作の小技集

# はじめに

UiPath Data Serviceは、業務データを構造化して扱える便利な機能であり、ワークフローの中で安定したデータ管理を可能にしてくれます。特に複数のプロセスで同じデータ構造を共有したい場合や、永続的にデータを保持しながら操作したいケースでは非常に役立ちます。

しかし、実際にStudioからエンティティを操作しようとすると、エンティティ型の変数の利用方法やチョイスセットの扱い方など、操作に迷うポイントがいくつかあります。
本記事では、UiPath StudioでData Serviceを扱う際に役立つ小技を具体的な例と共にご紹介します。日々の開発を少しでも快適にすすめるヒントになれば幸いです。

Data Serviceの基本的な使用方法については以下の記事に詳細な記述がありますので、そちらをご参照ください。

https://qiita.com/Kajiita/items/73c066056a17c774ffd4

# 小技集

## エンティティ型変数をData Tableに変換する

UiPath Studio では、Data Service のエンティティを操作する際、エンティティ型の変数を用いてデータを扱います。ただし、後続の処理や既存のワークフローとの互換性の観点から、これらのデータを DataTable 型に変換して利用したい場面も多くあります。

そのような場合に便利なのが、UiPath のアクティビティ 『コレクションをデータ テーブルに変換（Collection to DataTable）』 です。このアクティビティを使用することで、エンティティ型の変数（コレクション）を簡単に DataTable に変換することができます。

### 変換手順
1. 入力変数に『エンティティ レコードにクエリを実行』アクティビティ等で取得したエンティティ型の変数を直接指定
2. 出力変数に変換後の DataTable 型の変数を設定

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/59a3ddcb-42e1-9def-faea-b8d64b28f440.png)

この変換により、Data Service から取得したデータを DataTable として扱えるようになり、後続のフィルタ処理やExcel出力など、既存のアクティビティとの親和性が高まります。

https://docs.uipath.com/ja/activities/other/latest/workflow/collection-to-data-table

:::note 
DataTable の各列には、エンティティに定義された各フィールドの名前と、その値が自動的にマッピングされます。尚、列名はフィールドの表示名(Display Name)ではなく、名前(Name)である点に注意してください。
:::


## チョイスセットの値を参照する

### チョイスセットとは

チョイス セットは、UiPath Data Service においてエンティティのフィールドに設定できる、あらかじめ定義された選択肢の集合です。


チョイスセットを使用することにより、ユーザーが任意の文字列を入力するのではなく、決められた選択肢から選ぶため、データのばらつきや誤入力を防げます。また、UiPath Appsの入力画面と連携する際、ユーザーに対して直感的に選択肢を提供することができます。チョイス セットは Studio で Enum 値として使用できます。

https://docs.uipath.com/ja/data-service/automation-cloud/latest/user-guide/choice-sets


### Enum（列挙型）とは？
Enum（列挙型）とは、複数の関連する定数にわかりやすい名前を付けてグループ化する仕組みです。たとえば、以下のように定義されたEnumがあったとします：

``` vb
Enum Priority
    High    ' 0
    Medium  ' 1
    Low     ' 2
End Enum
```
この定義により、Priority.High は数値の 0、Priority.Low は 2 という整数として扱われます。
プログラム内では「意味のある名前」で扱いつつ、内部的には 整数（インデックス）として処理される点がポイントです。

UiPathでは、チョイスセットがこのEnumのように動作します。つまり、ラベル名（High, Medium, Low）は内部的に 0, 1, 2 といった数値に対応付けられており、クエリを実行する際にはこの**数値（インデックス）**を使用する必要があります。

### UiPath Studioで参照する方法

チョイスセットが設定されているフィールドを条件にクエリを実行する場合、ラベルや保存値そのものではなく、列挙型のインデックス（0, 1, 2...）を Decimal 形式の文字列で指定する必要があります。

ここでは、UiPath Studio上で指定のチョイスセット値に対応するインデックスを取得し、それをクエリ条件として使用する方法を紹介します。

例として、以下のようなエンティティとレコードから、Priority が Low のCaseを取得する場合を考えます。ここで、PriorityChoice はチョイスセットが設定されているフィールドであり、参照しているチョイスセット"Priority"には、上記の例の通り選択肢として"High", "Medium", "Low"が設定されているものとします。

エンティティ名：TestEntity
| CaseNumber | PriorityChoice |
|:-|:-|
| Case001 | Medium  |
| Case002 | Low  |
| Case003 | High  |


以下の2つの「代入」アクティビティで、対象となる "Low" のインデックスを取得します。
※1つの式にまとめても問題ありません。

#### 『代入』アクティビティ1
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/36f3c744-8a69-464f-8267-380f872c73af.png)

| 左辺 | 右辺 |
|:-|:-|
| value (Choice Set型) | CType([Enum].Parse(GetType(Priority), "Low"), Priority)  |

この式は、文字列 "Low" に対応する Priority Enumの値（= Priority.Low = 2）を取得します。


#### 『代入』アクティビティ2
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/7ca54dfa-f39a-42a7-ba1b-38fc0009729b.png)
| 左辺 | 右辺 |
|:-|:-|
| index (String型) | Array.IndexOf([Enum].GetValues(GetType(Priority)), value).ToString |

ここで、value に対応する インデックスを取得し、String型型として保存します。
これがクエリで使用する値です。

#### クエリ条件への設定

『エンティティ レコードにクエリを実行』アクティビティの条件に、上で取得した index を使用します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/e64e7a75-2ef8-4e1a-ace7-c9a05c5ac571.png)

:::note 
『エンティティ レコードにクエリを実行』アクティビティの条件にチョイスセットのインデックスを指定する際、Decimal型ではなく、String型で指定する必要があります。
:::


## C#コードで定義した型をワークフローに返す

UiPath Studioでは、Data Serviceで定義されたエンティティ型の変数を使用して、ワークフロー上で値を代入することが可能です。しかし、エンティティにフィールド数が多い場合や、代入条件が複雑な場合には、ワークフローが長くなりがちです。

このような場面では、コードソースファイル（C#）を使用することで、簡潔かつ柔軟に値を設定したエンティティレコードを作成できます。

ここでは、C#で定義した関数を使用してエンティティ型のレコードを生成し、それをワークフローに返す方法を紹介します。

:::note
コード化されたワークフローの出力引数ではエンティティ型変数をワークフローに直接返すことができないため、コードソースファイルを使用して記述します。
:::

https://docs.uipath.com/ja/studio/standalone/latest/user-guide/code-source-file


### C#コードソースファイルの作成

以下のようにクラス TestEntityBuilder を定義し、レコードを作成するメソッド CreateTestEntityRecord を用意します。

``` Csharp
using System;

namespace DataServiceOperationSample
{
    public class TestEntityBuilder
    {
        public TestEntity CreateTestEntityRecord(string in_CaseNumber, string in_Priority)
        {
            var newRecord = new TestEntity();
            newRecord.CaseNumber = in_CaseNumber;
            Priority value = (Priority)Enum.Parse(typeof(Priority), in_Priority);
            newRecord.PriorityChoice = value;

            return newRecord;
        }
    }
}
```

::: note
- Priority は Data Service により自動生成される Enum 型
- PriorityChoice は Choice Set 型のフィールド（Enumとして扱われる）
:::


### Studio側での設定（レコード生成）

C#コードを組み込んだ後、以下のように2つの代入アクティビティでレコードを生成します。

以下のように代入アクティビティを設定し、レコードを生成します。生成するレコードの例として、`CaseNumber: Case004`、`Priority: Medium`とします。

#### 『代入』アクティビティ1: クラスのインスタンス作成
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/d932fb32-dd24-4007-92ed-4ca1cd842d5f.png)

| 左辺 | 右辺 |
|:-|:-|
| newReturnEntityBuilder (TestEntityBuilder型) | New TestEntityBuilder |


#### 『代入』アクティビティ2: レコードの生成
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/f514b7c9-bc23-494c-b420-a9dbc07a010e.png)
| 左辺 | 右辺 |
|:-|:-|
| newRecord (TestEntity型) | newReturnEntityBuilder.CreateTestEntityRecord("Case004","Medium") |



### レコードのアップロード

上記で生成した変数 newRecord を『エンティティレコードを作成』の入力変数に指定し、レコードをエンティティに作成します。
※アクティビティの表示を"レコードビュー"に切り替えます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/69aab2d2-318a-4628-aba5-d14d2ea820d5.png)


## 1000件以上のレコードを取得する

「エンティティ レコードにクエリを実行」アクティビティでは、内部的に実行される API リクエストにおいて、一度のリクエストで取得できるレコード数の上限は1000件です。
そのため、クエリで取得または送信したいレコードが1000件を超える場合は、1000件単位で繰り返し処理を行う必要があります。

繰り返し処理では、「上限数」と「スキップ数」のプロパティを組み合わせることで、参照対象のレコード範囲を制御できます。

ここでは、1000件を超えるレコードを取得する際の基本的なワークフロー構成の一例をご紹介します。


### 処理の流れ
1. 取得したレコードを格納するIList<{エンティティ}>型の変数を定義する
1. `skip = 0`として初期化する
1. Do Whileの中で『エンティティ レコードにクエリを実行』アクティビティによりレコードを取得する
1. 取得したレコードを、ステップ1で定義したListに格納する
1. 2で定義した `skip` の値に取得したレコード数を足しこむ

### 繰り返し条件
Do While の繰り返し条件は `取得件数 = 上限数` であるかどうかです。
これにより、まだ取得されていないデータが存在する限りループを継続し、すべてのレコードを段階的に取得することができます。

### ワークフローの例
以下は、上記の処理をワークフローとして構成した例です。
取得したレコードをリストに追加するため、『繰り返し（コレクションの各要素）』および『コレクションに項目を追加』アクティビティを使用しています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/1cb5871c-d609-453d-a9b8-b1c132785d1d.png)


:::note
『複数のエンティティ レコードを作成』アクティビティ等、複数レコードを一括で作成・更新するアクティビティでも、同様に1000件を超える場合は分割処理が必要です。
:::

# その他

## 一時的なエラー回避にはリトライスコープを活用する

ネットワークの遅延や一時的な接続不良、APIレスポンスのタイムアウトなど、外部要因による一時的なエラーは完全に防ぐことができません。特に Data Service との通信やクラウドサービスとの連携処理では、安定性を考慮する必要があります。

このようなエラーに備える手段として、『リトライスコープ』アクティビティを使用することができます。クエリを実行する際等にエラーが頻発するような場合には有効な場面があります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3334074/a769176f-6c67-4740-b169-21e71ec3f2fa.png)

https://docs.uipath.com/ja/activities/other/latest/workflow/retry-scope

## Data ServiceのエンティティにUiPath以外の環境からアクセスする

Data Service APIを使用してアクセス可能です。詳細については以下の記事をご参照ください。

https://qiita.com/mstgsg/items/89fe27545b5ee353dca9

https://qiita.com/mstgsg/items/de00bff23d6d68968e2a



# 免責事項

- 本記事の内容は、執筆時点のUiPathの仕様に基づいて記載しています。将来的なバージョンアップ等により、動作や画面が変更される可能性があります
- 記事の内容は、個人の見解または確認結果であり、UiPath の公式見解ではありません 
- ここでご紹介するサンプルスクリプトはChatGPT等を利用して自動生成されたものをベースにしております。あくまで動作確認用として提示おり、本番環境での動作を保証するものではありません。実際の開発・運用に適用する際は、事前にテスト環境での動作確認を推奨します
- 本記事は2025年6月時点での情報を掲載しております


# おわりに

本記事では、UiPath Studio で Data Service を扱う際に知っておくと便利な小技をご紹介しました。日々の開発で「ちょっと面倒だけど工夫すればスマートにできそう」と思った場面に、少しでも役立てば幸いです。