# Function Hub

Function Hubは現在、初期ベータ版として提供されており、Adaloビルダーにはまだ完全に統合されていません。APIキーを生成するには、コマンドラインツールのcURLを使用し、アプリケーションIDを指定してください。

```
$ curl -X POST https://functionhub.adalo.com/api/keys \
-H "Content-Type: application/json" \
-d '{"app_id": "YOUR-APP-ID"}' \
{"api_key":"124TYghFYU9898123PRTNF"}%
```

APIキーはJSON形式のレスポンスとして返されます。上記の例では、キーは`124TYghFYU9898123PRTNF`です。このキーをコピーして、パスワード管理ツールに保存してください。

### Function Hubを使用したカスタムアクションの設定方法

AdaloアプリからFunction Hubの各エンドポイントを呼び出す手順は以下の通りです。

1. Adaloエディタでアプリを開く
2. アクションのトリガーとなるコンポーネント、またはスクリーンを選択する
3. 「**Custom Action**（カスタムアクション）」を追加する
4. **API Base URL**（ベースURL）を以下に設定する：`https://functionhub.adalo.com`
5. **Method**（メソッド）を設定する（エンドポイントの仕様に合わせて POST または GET を選択します。）
6. 特定の商品の**URLパス**を入力する（例：`/api/math/sort`）
7. **Headers**（ヘッダー）に以下を追加する：
   * **Key:** `X-API-Key`
   * **Value:** あなたのAPIキー
8. （JSONボディを含むPOSTリクエストの場合のみ）**Headers**に以下を追加する：
   * **Key:** `Content-Type`
   * **Value:** `application/json`
9. 各エンドポイントの説明に従って、**Body**または**URLパラメータ**を設定する
10. **Response**（レスポンス）設定にて、出力フィールド（例：`result`）をMagic Textやアプリ内のプロパティに紐付ける（マッピングする）

### 対応しているエンドポイント

現在、実用的なエンドポイントが限定的に利用可能です。ユーザーの要望に基づき、今後も機能を拡充していきます！

#### 数値のソート

カンマ区切りの数値リストを昇順で並べ替えます。

**ユースケース**

* スコアや評価のリストを並べ替える
* 価格を安い順から高い順に並べる
* コレクション内の数値データをランク付けする

| **Method**   | POST             |
| ------------ | ---------------- |
| **URL**      | `/api/math/sort` |
| **Auth（認証）** | 必須               |

**Request Body（リクエストボディ）**

| パラメータ     | 型      | 要件 | 説明                         |
| --------- | ------ | -- | -------------------------- |
| `numbers` | string | 必須 | カンマ区切りの整数（例：`"5,2,9,1,3"`） |

**例**

**リクエスト：**

```
POST /api/math/sort
Content-Type: application/json
X-API-Key: your-api-key

{
  "numbers": "5,2,9,1,3"
}
```

**レスポンス (200)：**

```json
{
  "result": "1,2,3,5,9"
}
```

**cURLとAPIキーを使用して、このエンドポイントをテストできます。**

```
curl -X POST https://functionhub.adalo.com/api/math/sort \
    -H "Content-Type: application/json" \
    -H "X-API-Key: your-api-key" \
    -d '{"numbers": "5,3,8,1,9,2"}'

  Response:

  {"result": "1,2,3,5,8,9"}
```

**数値を並べ替えるカスタムアクションの設定**

* **Method:** POST
* **URL:** `/api/math/sort`
* **Body:** `numbers`をカンマ区切りのリストに設定します。データベースから値を取得するには、マジックテキストを使用できます。
* **Output（出力）:** `result`をマップ化し、ソートされたリストを表示します。

#### テキストの置換

文字列内の特定の部分文字列をすべて置換します。

**ユースケース**

* ユーザー入力のクリーンアップ（不要な文字の削除）
* プレースホルダーテキストを動的な値に置換
* 表示されるコンテンツから機密性の高い単語を伏せ字にする

| **Method**   | POST                                               |
| ------------ | -------------------------------------------------- |
| **URL**      | `/api/string/replace/{string}/{search}/{replace?}` |
| **Auth（認証）** | 必須                                                 |

**URLパラメータ**

| パラメータ     | 要件 | 説明                            |
| --------- | -- | ----------------------------- |
| `string`  | 必須 | 変更する元のテキスト                    |
| `search`  | 必須 | 検索対象となる文字列                    |
| `replace` | 不要 | 置換後のテキスト。省略された場合、検索語句は削除されます。 |

**例**

**単語を置き換える：**

```
POST /api/string/replace/hello world/world/universe
X-API-Key: your-api-key
```

```json
{
  "result": "hello universe"
}
```

**単語を削除する（置き換えなし）：**

```
POST /api/string/replace/hello world/world
X-API-Key: your-api-key
```

```json
{
  "result": "hello "
}
```

**文字列を置換するカスタムアクションの設定**

* **Method:** POST
* **URL:** マジックテキストを使用して動的にパスを構築する：`/api/string/replace/{YourTextField}/{SearchTerm}/{ReplacementText}`
* **Output（出力）:** `result`をテキストプロパティまたは表示フィールドに割り当てる

#### テキストの操作

組み込みのオプションのいずれかを使用して、文字列を変換します。

**ユースケース**

* ユーザー名をタイトルケース（`capitalize`）に統一する
* メールアドレスを小文字で保存する
* 見出しを大文字で表示する

|              |                                           |
| ------------ | ----------------------------------------- |
| **Method**   | POST                                      |
| **URL**      | `/api/string/convert/{function}/{string}` |
| **Auth（認証）** | 必須                                        |

**URLパラメータ**

| パラメータ      | 要件 | 説明                                                        |
| ---------- | -- | --------------------------------------------------------- |
| `function` | 必須 | One of: `uppercase`, `lowercase`, `capitalize`, `reverse` |
| `string`   | 必須 | The text to transform                                     |

利用可能な機能

| 機能           | 説明説明             | 入力例           | 出力例           |
| ------------ | ---------------- | ------------- | ------------- |
| `uppercase`  | すべての文字を大文字に変換する  | `hello world` | `HELLO WORLD` |
| `lowercase`  | すべての文字を小文字に変換する  | `Hello World` | `hello world` |
| `capitalize` | 各単語の最初の文字を大文字にする | `hello world` | `Hello World` |
| `reverse`    | 文字列を逆順にする        | `hello`       | `olleh`       |

**例**

```
POST /api/string/convert/capitalize/john doe
X-API-Key: your-api-key
```

```json
{
  "result": "John Doe"
}
```

**エラーレスポンス**

関数名が無効な場合：

```json
{
  "error": "Invalid function"
}
```

ステータス: **404**

**テキストを操作するためのカスタムアクションの設定**

* **Method:** POST
* **URL:** `/api/string/convert/capitalize/{YourTextField}` —  `capitalize` を必要な関数に置き換える
* **Output（出力）:** `result`をテキストプロパティに割り当てる

#### テキストの連結

カンマ区切りのテキストを、スペース区切りの単一の文字列に結合します。

**ユースケース**

* 名、姓、および敬称を組み合わせてフルネームを作成する
* 通り名、都市名、州名、郵便番号のフィールドから住所を作成する
* 複数のテキストフィールドを1つの表示用文字列に統合する

| **Method**   | POST                             |
| ------------ | -------------------------------- |
| **URL**      | `/api/string/concatenate/{text}` |
| **Auth（認証）** | 必須                               |

**URLパラメータ**

| パラメータ  | 要件 | 説明                           |
| ------ | -- | ---------------------------- |
| `text` | 必須 | 結合するカンマ区切り値（例：`hello,world`） |

空の値は自動的に除外され、各セグメントの先頭と末尾の空白文字が削除されます。

**例**

```
POST /api/string/concatenate/John,Doe,Jr.
X-API-Key: your-api-key
```

```json
{
  "result": "John Doe Jr."
}
```

**テキストを連結するカスタムアクションの設定**

* **Method:** POST
* **URL:** 「Magic Text」を使ってパスを作成する：`/api/string/concatenate/{FirstName},{LastName},{Suffix}`
* **Output（出力）:** `result` をテキストプロパティ（例：フルネーム）に割り当てる

#### 時間差

2つの時間の差を計算します。

**ユースケース**

* 勤務時間の長さを計算する
* 2つの予定されたイベントの間隔を表示する
* 締め切りまでの残り時間を表示する

| **Method**   | GET                                                   |
| ------------ | ----------------------------------------------------- |
| **URL**      | `/api/temporal/between/{startTime}/{endTime}/{unit?}` |
| **Auth（認証）** | 必須                                                    |

**URLパラメータ**

| パラメータ       | 要件 | 説明                                                             |
| ----------- | -- | -------------------------------------------------------------- |
| `startTime` | 必須 | 開始時刻は24時間表記（`HH:MM`、例：`09:00`）                                 |
| `endTime`   | 必須 | 終了時刻は24時間表記（`HH:MM`、例：`17:30`）                                 |
| `unit`      | 不要 | 出力単位。デフォルト：`minutes`。オプション：`minutes`, `hours`, `seconds`, `hm` |

**単位オプション**

| 単位        | レスポンスキー         | 説明           | 例 (09:00 から 10:30) |
| --------- | --------------- | ------------ | ------------------ |
| `minutes` | `minutes`       | 合計分数         | `90`               |
| `hours`   | `hours`         | 整数時間（切り捨て）   | `1`                |
| `seconds` | `seconds`       | 合計秒数         | `5400`             |
| `hm`      | `hours_minutes` | `H:MM`形式の時と分 | `"1:30"`           |

**例**

**デフォルト（分）：**

```
GET /api/temporal/between/09:00/17:30
X-API-Key: your-api-key
```

```json
{
  "minutes": 510
}
```

**時と分：**

```
GET /api/temporal/between/09:00/17:30/hm
X-API-Key: your-api-key
```

```json
{
  "hours_minutes": "8:30"
}
```

**時間差を計算するカスタムアクションの設定**

* **Method:** GET
* **URL:** 「Magic Text」を使ってパスを作成する：`/api/temporal/between/{StartTimeField}/{EndTimeField}/hm`
* **Output（出力）:** `hours_minutes`（または選択した単位に応じて`minutes`, `hours`, `seconds`）をテキストまたは数値のプロパティにマッピングする

#### 合計値

カンマ区切りの数値のリストの合計を計算します。

**ユースケース**

* 注文の明細を合計する
* 値のリストから累計を計算する
* 複数のカテゴリにわたるスコアを合計する

|              |                 |
| ------------ | --------------- |
| **Method**   | POST            |
| **URL**      | `/api/math/sum` |
| **Auth（認証）** | 必須              |

**Request Body（リクエストボディ）**

| パラメータ     | 型      | 要件 | 説明                     |
| --------- | ------ | -- | ---------------------- |
| `numbers` | string | 必須 | カンマ区切りの整数（例：`"1,2,3"`） |

**例**

**リクエスト：**

```
POST /api/math/sum
Content-Type: application/json
X-API-Key: your-api-key

{
  "numbers": "1,2,3"
}
```

**レスポンス (200)：**

```json
{
  "result": 6
}
```

**Adaloの設定**

* **Method:** POST
* **URL:** `/api/math/sum`
* **Body:** `numbers`をカンマ区切りのリストとして設定。データベースから値を取得するには、Magic Textを使用できます。
* **Output（出力）:** `result`を数値プロパティにマッピングする

***

#### 数値の平均

カンマ区切りの数値のリストの平均（算術平均）を計算します。

|              |                     |
| ------------ | ------------------- |
| **Method**   | POST                |
| **URL**      | `/api/math/average` |
| **Auth（認証）** | 必須                  |

**Request Body（リクエストボディ）**

| パラメータ     | 型      | 要件 | 説明                     |
| --------- | ------ | -- | ---------------------- |
| `numbers` | string | 必須 | カンマ区切りの整数（例：`"2,4,6"`） |

**例**

**リクエスト：**

```
POST /api/math/average
Content-Type: application/json
X-API-Key: your-api-key

{
  "numbers": "2,4,6"
}
```

**レスポンス (200)：**

```json
{
  "result": 4
}
```

**Adaloの設定**

* **Method:** POST
* **URL:** `/api/math/average`
* **Body:** `numbers`をカンマ区切りのリストとして設定。データベースから値を取得するには、マジックテキストを使用できます。
* **Output（出力）:** `result`を数値プロパティにマッピングする

**ユースケース**

* 複数のレビューから平均評価を算出する
* 一連の評価から平均スコアを求める
* 商品のリストから平均価格を算出する

***

#### 最小値

カンマ区切りの数値のリストから、最も小さい数値を求めます。

**ユースケース**

* 商品のセットの中から最も安い価格を探す
* 最低のスコアや評価を特定する
* 在庫がある中で最も早い数量を特定する

|              |                 |
| ------------ | --------------- |
| **Method**   | POST            |
| **URL**      | `/api/math/min` |
| **Auth（認証）** | 必須              |

**Request Body（リクエストボディ）**

| パラメータ     | 型      | 要件 | 説明                     |
| --------- | ------ | -- | ---------------------- |
| `numbers` | string | 必須 | カンマ区切りの整数（例：`"5,3,1"`） |

**例**

**リクエスト：**

```
POST /api/math/min
Content-Type: application/json
X-API-Key: your-api-key

{
  "numbers": "5,3,1"
}
```

**レスポンス (200)：**

```json
{
  "result": 1
}
```

**Adaloの設定**

* **Method:** POST
* **URL:** `/api/math/min`
* **Body:** `numbers`をカンマ区切りのリストに設定。データベースから値を取得するには、マジックテキストを使用できます。
* **Output（出力）:** `result`を数値プロパティにマッピングする

***

#### 最大値

カンマ区切りの数値のリストから、最大の数値を求めます。

**ユースケース**

* 最高入札額または最高売出価格の特定
* ランキングにおける最高スコアの特定
* 会場のリストから最大収容人数の算出

|              |                 |
| ------------ | --------------- |
| **Method**   | POST            |
| **URL**      | `/api/math/max` |
| **Auth（認証）** | 必須              |

**Request Body（リクエストボディ）**

| パラメータ     | 型      | 要件 | 説明                     |
| --------- | ------ | -- | ---------------------- |
| `numbers` | string | 必須 | カンマ区切りの整数（例：`"5,3,1"`） |

**例**

**リクエスト：**

```
POST /api/math/max
Content-Type: application/json
X-API-Key: your-api-key

{
  "numbers": "5,3,1"
}
```

**レスポンス (200)：**

```json
{
  "result": 5
}
```

**Adaloの設定**

* **Method:** POST
* **URL:** `/api/math/max`
* **Body:** `numbers`をカンマ区切りのリストとして設定。データベースから値を取得するには、マジックテキストを使用できます。
* **Output（出力）:** `result`を数値プロパティにマッピングする

***

#### 割合

ある数値が別の数値に対して何パーセントを占めるかを計算します。

**ユースケース**

* 完了進捗の表示（例：60件のタスクのうち15件完了＝25%）
* 割引率の計算
* 目標の達成率の表示

|              |                        |
| ------------ | ---------------------- |
| **Method**   | POST                   |
| **URL**      | `/api/math/percentage` |
| **Auth（認証）** | 必須                     |

**Request Body（リクエストボディ）**

| パラメータ    | 型       | 要件 | 説明               |
| -------- | ------- | -- | ---------------- |
| `number` | numeric | 必須 | 部分の値（例: `"50"`）  |
| `total`  | numeric | 必須 | 全体の値（例: `"200"`） |

**例**

**リクエスト：**

```
POST /api/math/percentage
Content-Type: application/json
X-API-Key: your-api-key

{
  "number": "50",
  "total": "200"
}
```

**レスポンス (200)：**

```json
{
  "result": 25
}
```

**Adaloの設定**

* **Method:** POST
* **URL:** `/api/math/percentage`
* **Body:** 「部分」の欄には`number`を、「合計」の欄には`total`を入力してください。データベースから値を取得するには、Magic Text を使用できます。
* **Output（出力）:** `result`を数値プロパティにマッピングする

### ヒントとベストプラクティス

* **特殊文字のURLエンコード** — テキストにスペースや特殊文字が含まれる場合、パスパラメータではURLエンコードが必要です（例：`hello world` は `hello%20world` となります）。Adaloで「Magic Text」を使用する場合、これは自動的に処理されます。
* **表示には `hm` を使用する** — `hm` 単位は `1:30` のような人間が読みやすい形式を返します。これはアプリのUIで「所要時間（期間）」を表示するのに最適です。
* **動的テキストには「Concatenate（結合）」を活用する** — concatenate エンドポイントを使用すると、Adaloのデータベースにある複数のフィールドを組み合わせて、フルネーム、住所、その他の任意のテキストを作成できます。
* **1つのアプリにつき1つのキー** — Adaloアプリ1つにつき、1つのAPIキーを作成してください。そのアプリ内のすべてのカスタムアクションで同じキーを使用します。
* **インタラクティブ・ドキュメントでテストする** — カスタムアクションを設定する前に、ベースURLの `/docs/api` にアクセスして、ブラウザ上で直接エンドポイントのテストを行うことができます。