# Bubble

Bubbleの**API Connector**はBubbleサーバーから呼び出しを送信するため、ここでは公開キーではなく「サーバーのみ」のキーが必要になるよ。以下のリクエストは、呼び出しが構成するそのままの形式で本番環境に送信される。Bubbleのステップは2026-09-17時点のBubbleマニュアルに基づいて記述されており、API Connector自体は無料プランに含まれているよ。

まず、[自動化キー](/integrations/#ключ-для-автоматизації)セクションで説明されているように、`chart`スコープでキーを作成してね。

## 1. コレクションを作成する

API Connectorプラグインで**+ New**をクリックし、コレクションを記入してね：

- **Collection name**: `AstroWay`。Bubbleマニュアルは、コレクション名がアプリケーションのクライアントコードに含まれるため、シンプルに保つよう警告しているよ。
- **Authentication**: **Private key in header**、ヘッダー名 `X-Api-Key`、値はあなたのキー。

**None or self-handled**のままにする場合、**+ Add a shared header**ボタンで**Shared headers for all calls**にキーを追加し、**Private**にチェックを入れてね。どちらの場合も、キーはサーバーに残るよ。

<Aside type="caution" title="キーをBodyに絶対に入れないでください">
BubbleはBodyをクライアントセーフとして文書化しているよ。その値は呼び出し時に訪問者のブラウザに送信されるんだ。URLはそこには含まれず、**Private**にチェックが入ったヘッダーも同様だよ。JSONボディに挿入されたキーは、すでに公開されたキーであると見なされるよ。
</Aside>

## 2. 呼び出しを追加する

コレクション内に呼び出しを追加し、それを記入してね：

- **Call name**: `Natal chart`。
- **Use as**: ワークフロー用には**Action**、ページが直接データを読み込む場合は**Data**。
- **Method**: `POST`。
- **URL**:

  ```
  https://api.astroway.info/v1/chart
  ```

- **Body type**: **JSON**。
- **Body**: 以下のJSON。角括弧はBubbleのパラメータ構文であり、それぞれがボディの下にエントリを作成するよ。

```json
{
  "date": "<date>",
  "time": "<time>",
  "timezone": "<timezone>",
  "latitude": "<latitude>",
  "longitude": "<longitude>"
}
```

ボディの下で、アプリケーションがそれらを設定できるように、5つのパラメータすべてから**Private**のチェックを外してね。そして表の値をデフォルトとして指定するんだ。次に**Initialize call**をクリックしてね。

| パラメータ | 初期化用の値 |
|---|---|
| `date` | `1990-05-15` |
| `time` | `14:30:00` |
| `timezone` | `Europe/Kyiv` |
| `latitude` | `50.45` |
| `longitude` | `30.52` |

初期化とは、Bubbleに応答の形式を教えるものであり、マニュアルは、そのためにサンプルデータを使用するよう求めているよ。これら5つの値がそれにあたるんだ。正しい応答には、値がtrueの`ok`と、`planets`、`houses`、`input`を含む`data`オブジェクトが含まれるよ。

パラメータを追加または名前変更した後、初期化を繰り返す必要があるよ。応答スキーマはこのステップで記憶されるためなんだ。

## 3. 応答を読み取る

初期化後、Bubbleはタイプと包含チェックボックス付きで応答フィールドを表示するよ。最も一般的な3つの値は次のとおり：

- **アセンダント**: `data > houses > ascendant`。
- **太陽**: `data > planets`の最初のエントリ、その`longitude`。
- **月**: 2番目のエントリ、その`longitude`。
- **使用されたオフセット**: `data > input > timezoneOffset`。上記の例では`4`だよ。その日付のキエフはUTC+4だったためなんだ。

サインは、経度を30で割って切り捨てたものであり、12の名称のリストにおけるインデックスとして機能するよ。式では、`data's houses's ascendant`を30で割り、整数部分を取り、option setまたは12のサインのリストでその数を見つけるんだ。例えば、アセンダント`159.26`は`5`、つまり乙女座を与えるよ。

## エラー

ワークフローの失敗を処理したい場合、それを停止させるのではなく、呼び出しで**Include errors in response &amp; allow workflow actions to continue**にチェックを入れてね。Bubbleは、初期化後にこのオプションを切り替えると応答の形式が変わるため、初期化を繰り返す必要があると述べているよ。

- **`400 INVALID_FIELD`と`details`に`timezone`**: ゾーンが空であるか、`EST`のような略語であるか、ゾーン名ではない。
- **`400`と`details`に`date`または`time`**: 形式が`YYYY-MM-DD` / `HH:MM:SS`ではない。日付に対する`:formatted as`演算子が、呼び出し前にこれを修正するよ。
- **`403 ENDPOINT_NOT_IN_SCOPE`**: キーのスコープに`chart`がない。
- **`429 KEY_BUDGET_EXHAUSTED`**: キーが自身の予算を使い果たした。ダッシュボードでそれを引き上げてね。

<Aside type="note">
Bubbleは共有インフラストラクチャから呼び出しを送信するため、そのアドレスは他のBubbleアプリケーションと共有されるよ。私たちの制限はアドレスではなくキーごとにカウントされるため、あなたのクォータを消費することはないんだ。APIはジオコーディングを行わないよ。座標はあなたの独自のフィールドから取得されるか、または、あなたがキーを持っているジオコーディングサービスから取得されるんだ。
</Aside>