> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sync.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API コネクタ
export const CommonAuthSchemeNone = ({siteName = "CData Sync", siteNameShort = "Sync", datasource = "the data source"}) => {
return <>
認証なしで接続するには、Auth Scheme でNone を選択します。追加のプロパティは必要ありません。
;
};
export const cloudEnv = false;
export const siteNameShort = "Sync";
export const siteName = "CData Sync";
export const datasource = "API";
export const pageTitle = "API";
export const oauthschemes = "OAuth";
{siteName} API コネクタは、API に直接接続する簡単で完全にカスタマイズ可能な方法を提供します。接続を確立したら、組み込みのウィザードを使用して、後でジョブで使用できるテーブル形式でAPI レスポンスデータを構成します。
## API コネクタを追加する
{siteName} が{datasource} のデータを使用できるようにするには、まずコネクタを追加する必要があります：
1. {siteNameShort} ダッシュボードの**接続**ページを開きます。
2. **接続を追加**をクリックして**コネクタを選択**ページを開きます。
3. **データソース**タブをクリックして**API** の行を探します。
4. その行の右端にある**接続を設定**アイコンをクリックします。
5. **接続を追加**ダイアログボックスに接続名を入力します。
6. **追加**をクリックしてコネクタの**設定**タブを開きます。
## API への認証
コネクタを追加したら、必要なプロパティを設定します。
{siteName} は、いくつかの方法で{pageTitle} への認証をサポートしています。以下から認証方法を選択し、認証の詳細を含む該当セクションに進みます。
* [**None**](#none)
* [**Basic**](#basic)
* [**Digest**](#digest)
* [**Bearer Token**](#bearer-token)
* [**OAuth**](#oauth)
* [**OAuth Password**](#oauth-password)
* [**OAuth Client**](#oauth-client)
### None
### Basic
ユーザー資格情報で接続するには、次のプロパティを指定します：
* **Auth Scheme：** **Basic** を選択。
* **User：** API アカウントへの認証に使用するユーザー名を入力。
* **Password：** API アカウントへの認証に使用するパスワードを入力。
### Digest
ユーザー資格情報で接続するには、以下を指定します：
* **Auth Scheme：** **Digest** を選択。
* **User：** API アカウントへの認証に使用するユーザー名を入力。
* **Password：** API アカウントへの認証に使用するパスワードを入力。
### Bearer Token
OAuth アクセストークンで接続するには、以下を指定します：
* **Auth Scheme：** **Bearer Token** を選択。
* **OAuth Access Token：** OAuth を使用する際に接続に使用するアクセストークンを入力。
### OAuth
OAuth カスタムクレデンシャルで接続するには、次のプロパティを指定します：
* **Auth Scheme：** **OAuth** を選択。
* **OAuth Client Id：** OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントId を入力。
* **OAuth Client Secret：** OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントシークレットを入力。
* **OAuth Authorization URL：** サインイン時にリクエストトークンを認証するために必要なOAuth 認証URL を入力。
* **OAuth Access Token URL：** アクセストークンのリクエストを行うURL を入力。
OAuth 1.0 では、認可されたリクエストトークンはアクセストークンと交換されます。
* **OAuth Refresh Token URL：** アクセストークンの有効期限が切れたときにリフレッシュトークンが新しいアクセストークンと交換されるURL を入力。
データソースによっては、このURL はアクセストークンURL と同じである可能性があります。
* （オプション）**Scope：** 最初のアクセストークンとリフレッシュトークンを取得するために必要なスコープを入力。
### OAuth Password
OAuth カスタムクレデンシャルで接続するには、次のプロパティを指定します：
* **Auth Scheme：** **OAuthPassword** を選択。
* **User：** API アカウントへの認証に使用するユーザー名を入力。
* **Password：** API アカウントへの認証に使用するパスワードを入力。
* **OAuth Client Id：** OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントId を入力。
* **OAuth Client Secret：** OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントシークレットを入力。
* **OAuth Access Token URL：** アクセストークンのリクエストを行うURL を入力。
OAuth 1.0 では、認可されたリクエストトークンはアクセストークンと交換されます。
* （オプション）**OAuth Refresh Token URL：** アクセストークンの有効期限が切れたときにリフレッシュトークンが新しいアクセストークンと交換されるURL を入力。
データソースによっては、このURL はアクセストークンURL と同じである可能性があります。
* （オプション）**Scope：** 最初のアクセストークンとリフレッシュトークンを取得するために必要なスコープを入力。
### OAuth Client
OAuth カスタムクレデンシャルで接続するには、次のプロパティを指定します：
* **Auth Scheme：** **OAuthClient** を選択。
* **OAuth Client Id：** OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントId を入力。
* **OAuth Client Secret：** OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントシークレットを入力。
* **OAuth Access Token URL：** アクセストークンのリクエストを行うURL を入力。
OAuth 1.0 では、認可されたリクエストトークンはアクセストークンと交換されます。
* （オプション）**OAuth Refresh Token URL：** アクセストークンの有効期限が切れたときにリフレッシュトークンが新しいアクセストークンと交換されるURL を入力。
データソースによっては、このURL はアクセストークンURL と同じである可能性があります。
* （オプション）**Scope：** 最初のアクセストークンとリフレッシュトークンを取得するために必要なスコープを入力。
## 接続を完了する
接続を完了するには：
1. **Test URL** に認証スキームを検証するためのURL を入力します。
2. 接続および作成するテーブルの両方に適用されるグローバルヘッダーを定義します。詳しい手順については、[ヘッダーを追加](#ヘッダーを追加)を参照してください。
3. 必要に応じて、**Other** プロパティ（**Miscellaneous** セクションの下）で追加の設定を行います。このプロパティは、通常の使用および機能には必要ありません。ただし、必要な場合は、接続に必要な追加設定のリストをセミコロンで区切って入力してください。
4. **Advanced** タブで詳細な接続設定を定義します。（ただし、ほとんどの場合、これらの設定は必要ありません。）
5. {oauthschemes} で認証する場合は、**{datasource} への接続**をクリックして{pageTitle} アカウントに接続します。
6. **作成およびテスト**をクリックして接続を作成します。
接続の作成に成功したら、次のセクションで説明するように、テーブル、疑似カラム、フィルタ、およびページネーションを追加できます：
* [テーブルを追加](#テーブルを追加)
* [疑似カラムを追加](#疑似カラムを追加)
* [フィルタを追加](#フィルタを追加)
* [ページネーションを追加](#ページネーションを追加)
## ヘッダーを追加
接続ページの**ヘッダーを追加**セクションでは、接続および作成するテーブルの両方に適用されるグローバルヘッダーを定義できます。
すべてのAPI コールで送信されるHTTP ヘッダーを追加するには、次のプロパティを指定します：
* **Name：** **名前**フィールドにヘッダー名を入力（例：**Token**）。
* **Value：** ヘッダーの値を入力（例：トークン）。
さらにヘッダーを追加する場合は、**ヘッダーを追加**をクリックしてヘッダー名と値を指定します。
## テーブルを追加
API に接続すると、テーブル形式でAPI データを作成、表示、設定できます。
テーブルを作成するには：
1. API 接続を開いて**テーブル**タブをクリックし、**新規テーブル**ページを開きます。
2. **テーブルを追加**をクリックして、新規テーブルの作成を開始します。
3. **リクエストURL** セクションで：
1. **リクエストURL** リストから、リクエストする方法（**GET** または**POST**）を選択します。
2. 次の例に示すように、選択したメソッドの右側にある空白フィールドにAPI エンドポイントのURL を入力します：
メソッドに**POST** を選択した場合、ボディおよびコンテンツタイプの両方を指定する**必要**があります。
4. **フォーマット**のオプション（**JSON** または**XML** のいずれか）を選択します。
5. このテーブルに対するすべてのAPI リクエストで送信されるURL パラメータを追加します。
パラメータを追加するには：
1. **パラメータ**タブにある**パラメータを追加**をクリックします。
2. **名前**フィールドにパラメータ名（例：**Country**）を入力します。
3. **値**フィールドにパラメータ値（例：**United States**）を入力します。
さらにパラメータを追加するには、上の手順を繰り返します。
6. テーブルへのすべてのAPI リクエストで送信されるHTTP ヘッダーを追加します。これらのヘッダーは、API コネクタ自体を設定するときに追加するヘッダーに加えて追加されます。
ヘッダーを追加するには：
1. **ヘッダー**タブにある**ヘッダーを追加**をクリックします。
2. **名前**フィールドに名前（例：**Year**）を入力します。
3. **値**フィールドに値（例：**2020**）を入力します。
さらにヘッダーを追加するには、上の手順を繰り返します。
7. **テーブル詳細**カテゴリで、**テーブルを設定**ボタンをクリックします。このアクションにより、次の例に示すように、API レスポンスをプレビューできる**テーブルを設定**ダイアログボックスが開きます：
8. **次へ**をクリックします。
9. テーブルの繰り返し要素を少なくとも1つ選択します。*繰り返し要素*は、行として使用される繰り返し項目を含むAPI レスポンスの要素のパスです。{siteNameShort} は検出された各配列をレスポンスデータで返すので、複数のパスを選択することができます。この例では、**source** が繰り返し要素です。
{siteNameShort} は可能な繰り返し要素をインテリジェントに判断しようとしますが、特定のシナリオでは検出することができません。そのような場合は、次のようにカスタム**繰り返し要素**パスを設定する必要があります：
1. **カスタム繰り返し要素を使用**（ダイアログボックスの右上隅）をクリックします。
2. **繰り返し要素を追加**をクリックします。
3. 繰り返したい要素のパスを入力します。
10. **次へ**をクリックします。
11. 含める特定のカラムを選択します。
すべてのカラムを含めるには、カラムリストの右上にある**すべて選択**をクリックします。
12. **次へ**をクリックします。これにより、ダイアログボックスに**テーブルをプレビュー**タブが開き、選択したカラムを含むテーブルが表示されます。
13. **テーブル名**フィールドにテーブルの名前を入力します。
14. **Confirm** をクリックし、テーブルの選択内容を保存します。
15. **保存**（**新規テーブル**ページの右上隅）をクリックして、API コネクタページ上のテーブルへのリンクを保存します。
## 疑似カラムを追加
*疑似カラム*はテーブルカラムの動作を模倣しますが、疑似カラムはソーステーブルやAPI に物理的に格納されません。これらのカラムを使用すると、API に（SQL WHERE 句経由で）送信されるリクエストを変更できますが、その値は同期先テーブルには複製されません。
{siteNameShort} で疑似カラムを作成するには：
1. API コネクタから**テーブル > タスク**を選択します。
2. **タスク**ページ下部の**テーブル詳細**セクションに移動し、**疑似カラム**タブをクリックします。
3. **疑似カラムを追加**をクリックします。
4. **カラム名**テキストボックスに、疑似カラムの名前を入力します。次に、**データ型**リストから適切なデータ型を選択します。
上の画像で示すように、**アウトプット**チェックボックスをON にすることで、API テーブルの結果内に疑似カラムを出力することを選択できます。さらに、タスクのWHERE 句に疑似カラムを含めることを必須にしたい場合は、**必須**チェックボックスをON にします。タスクがWHERE 句に疑似カラムを含めない場合、{siteNameShort} は次の例のようなエラーメッセージを生成します：
疑似カラムを削除するには、疑似カラム行の最後にある**削除**アイコンをクリックします。
5. **保存**をクリックします。
## API コネクタテーブルのカラム属性の変更
{siteNameShort} アプリケーションでは、テーブルページの**テーブル詳細**セクションから、API コネクタテーブルの特定のカラム属性（カラムサイズ、精度、スケール）を編集できます。これらの設定は接続設定に保存され、バックアップ / 復元およびジョブインポート / エクスポート処理中に保持されます。
* **カラムサイズ：** String およびBinary 型で使用できます（デフォルトサイズは2000）。
* **精度：** Time、DateTime、Decimal、Float、Double 型で使用できます。
* **スケール：** Decimal 型でのみ使用できます。
レプリケーションは更新された定義で正しく動作し、新しいビルドへのアップグレードは既存の機能に影響しません。
カラム属性を変更するには、API 接続を開いて次の手順に従います：
1. **テーブル**タブをクリックします。既存のテーブルを編集するか、新しいテーブルを作成できます。
2. 編集するテーブルの名前をクリックします（または**テーブルを設定**をクリックして新しいテーブルを作成します）。
3. テーブルページの**テーブル詳細**セクションで、変更するデータカラムを見つけ、テーブルの**データ型**カラムでその属性を編集します。
次の例には、String（カラムサイズ）、Decimal（スケール）、Double（精度）型を使用し、そのデフォルト値が変更されたデータカラムが含まれています：
4. テーブルページの上部にある**保存**をクリックして、変更を保存します。
## フィルタを追加
カラムを持つテーブルを作成したら、クエリ中にWHERE 句が発行されたときのAPI コネクタの動作を定義するフィルタを作成できます。フィルタは、フィルタリング処理をサーバー側のAPI に委任することでパフォーマンスを向上させます。フィルタを含めない場合、クエリオプションは代わりに{siteNameShort} によって処理されます。
### フィルタの作成
テーブルの各カラムにフィルタを作成できます。
フィルタを作成するには：
1. 以下で示すように、**新規テーブル**ページにある**フィルタ**タブをクリックします。
2. **カラム**リストの下にある**フィルタを追加**をクリックします。
3. フィルタしたいカラムを**カラム**リストから選択します。
4. **Operator** リストから条件を選択します。次のオプションから選択可能です：
* **次と等しい**
* **次と等しくない**
* **次より小さい**
* **次より小さいか等しい**
* **次より大きい**
* **次より大きいか等しい**
5. **Type** リストから種類（**パラメータ**または**ヘッダー**）を選択します。次に、カラム名と一致しない場合はパラメータ名またはヘッダー名を入力します。
6. **保存**（ページ右上）をクリックしてフィルタを保存します。
次の例は、Reports テーブル内のレコードをレコードの作成日でフィルタリングするクエリを処理するフィルタを作成する方法を示しています。
**クエリ例**
```sql theme={null}
SELECT * FROM Reports WHERE CreatedDate > 2022-12-31
```
このテーブルにフィルタが定義されていない場合、コネクタはAPI からすべての行を読み取り、指定された**CreatedDate** カラムでメモリ内のリストをフィルタリングすることによって、メモリ内でこのフィルタを処理します。ただし、この例のAPI はサーバー側でこのタイプのフィルタリングをサポートしているため、パフォーマンスを大幅に向上させることができます。
次の例は、このクエリがAPI にどのように見えるかを示しています：
```
https://www.mycustomapi.org/api/reports?$startdate=2022-12-31
```
コネクタがこのフィルタをAPI に送信する方法を指定するには、次のフィールドを指定する必要があります：
* **Column：** CreatedDate
* **Operator：** Greater Than
* **Filter Type：** Parameter
* **Parameter Name：** startdate
これらの仕様は、CreatedDate カラムにGreater Than 演算子が指定されている場合、API リクエストのフィルタ値にstartDate URL パラメータを含めるよう接続に指示します。
### **行ごとのリクエスト**機能を使用したデータのフィルタリング
{siteNameShort} アプリケーションでは、**行ごとのリクエスト**機能を使用してデータをサブセット化できます。**行ごとのリクエスト**により、SQL IN 句を使って{siteNameShort} がフィルタ値ごとに個別のリクエストを渡すことができます。この機能は、子データセットをクエリする際に、そのクエリが親データセットの識別子（Id）が必要な場合に便利です。例えば、請求書データセット（親）から、ラインアイテム（子）を別々の行として1つの同期先テーブルに分割したいとします。次のクエリは、請求書Id 値に対する個別のリクエストを動的に渡します：
```sql theme={null}
REPLICATE [InvoiceLineItems] SELECT * FROM [InvoiceLineItems] WHERE InvoiceID IN ('1', '2', '3')
```
さらに、フィルタ内でInner SELECT クエリを使用して請求書Id の動的リストを渡すことができます：
```sql theme={null}
REPLICATE [InvoiceLineItems] SELECT * FROM [InvoiceLineItems] WHERE InvoiceID IN (SELECT Id FROM [Invoices])
```
**行ごとのリクエスト**機能を有効にするには：
1. リクエストURL を変更して、中かっこ内に一意のレコード識別子カラムの名前を含めます。中かっこ内にカラム名を追加すると、**リクエストURL**テキストボックス右端の上に**行ごとのリクエストが検出されました**が表示されます。
2. **テーブルを設定**をクリックします。
3. 一意のレコード識別子カラムのサンプル値を入力します。
4. [テーブルを追加](#テーブルを追加)セクションの手順7～13に従います。
一意のレコード識別子カラム（大文字小文字を区別）と一致するカラムまたは疑似カラムが存在することを確認してください。一致しない場合、{siteNameShort} は警告を表示します。
5. **保存**（**新規テーブル**ページの右上）をクリックします。
## ページネーションを追加
{siteNameShort} は、複数の種類のページング実装をサポートしています。ページネーションタイプを追加するには：
1. **ページネーション**タブをクリックします。
2. **Type** リストからページネーションの種類を選択します。次の種類から選択可能です：
* **None：** API リクエストが1つのレスポンスで完全なデータセットを返す場合は、このタイプを選択。
* **Offset：** API リクエストがページング用のレコードオフセットパラメータを提供する場合は、このタイプを選択。詳しくは、[Offset](#offset)を参照してください。
* **Number：** API リクエストに現在のページ番号を指定するパラメータが含まれている場合は、このタイプを選択。詳しくは、[Number](#number)を参照してください。
* **Token：** API レスポンスに次のページ用のトークンが含まれている場合は、このタイプを選択。詳しくは、[Token](#token)を参照してください。
* **URL：** API レスポンスに次のページ用のURL が含まれている場合は、このタイプを選択。詳しくは、[URL](#url)を参照してください。
3. **保存**（ページ右上）をクリックしてページネーションの設定を保存します。
### Offset
**Offset** を選択した場合は、次のプロパティを指定する必要があります：
* **Offset Parameter：** API リクエストでオフセットを定義するURL パラメータの名前を入力。
* **Page Size：** ページごとに取得したいレコード数を入力。API コネクタは、この値を使用してオフセットを計算します。
* （オプション）**Page Size Parameter：** ページごとに取得するレコード数を定義するURL パラメータの名前を入力。ページサイズを制御するパラメータがない場合は、**Page Size Parameter** を設定する必要はありません。ただし、その場合は、**Page Size** をデフォルトのページサイズに設定する必要があります。
**例**
次のリクエストでは、**Offset Parameter** は**pageOffset** に、**Page Size Parameter** は**pageSize** に、**Page Size** は**1000** に設定されています。この例では、コネクタがオフセットを自動的にインクリメントするため、データのページ6に対するリクエストを示しています：
```
https://myapi?pageOffset=5000&pageSize=1000
```
### Number
**Number** を選択した場合は、次も指定する必要があります：
* **Page Number Parameter：** ページ番号を定義するURL パラメータの名前を入力。
* （オプション）**Page Size Parameter：** ページサイズを定義するURL パラメータの名前を入力。
* （オプション）**Page Size：** ページごとに取得したいレコード数を入力。
**例**
次のリクエストでは、**Page Number Parameter** は**pageNum** に、**Page Size Parameter** は**pageSize** に、**Page Size** は**1000** に設定されています。この例では、コネクタがページを自動的にインクリメントするため、データのページ6に対するリクエストを示しています：
```
https://myapi?pageNum=6&pageSize=1000
```
### Token
**Token** を選択した場合は、次を指定する必要があります：
* **Token Path：** 次ページのトークンを定義するAPI レスポンスのパスを入力。
* （オプション）**Has More Path：** レコードが使用可能かどうかを定義するAPI レスポンスのパスを入力。
* **Token Source：** この設定は、トークンをURL パラメータとしてリクエストで送信するか、リクエストボディで送信するかを決定します。必要なオプションを選択してください：
* **Request Path：** {siteNameShort} がページングトークンを設定するリクエストボディのパスを入力。
* **URL Parameter：** {siteNameShort} がページングトークンに渡すURL パラメータの名前を入力。
**URL パラメータの使用例**
次のリクエストでは、**URL Parameter** は**pageToken** に、**Token Path** は **/results/nextpagetoken** に設定されています。
**リクエスト：** `https://myapi?pageToken=123456`
**レスポンス：**
```json theme={null}
{
"results": [
{
"rows": [
{
"id": "123",
"name": "Acme",
"country": "United States",
"no_employees": 500
}
],
"nextpagetoken": 123457
}
]
}
```
**リクエストパスの使用例**
次のリクエストでは、**Request Path** は **/request/pageToken** に、**Token Path** は **/results/nextpagetoken** に、**Has More Path** は **/results/morePages** に設定されています。
**リクエストボディ**
```json theme={null}
{
"request": [
{
"country": "United States",
"pageToken": 123456
}
]
}
```
**レスポンス**
```json theme={null}
{
"results": [
{
"rows": [
{
"id": "123",
"name": "Acme",
"country": "United States",
"no_employees": 500
}
],
"nextpagetoken": 123457,
"morePages": true
}
]
}
```
### URL
**URL** を選択した場合は、URL ソースも選択する必要があります：
* **Header Name：** 次ページURL がリンクヘッダーとともにレスポンスヘッダーに渡される場合は、ヘッダー名を入力。
* **Request Path：** 次ページURL を定義するAPI レスポンスのパスを入力。この値はXPath 記法で指定する必要があります。次の例を参照してください。
**リクエストパスの使用例**
次の例では、**Request Path** は **/results/nextpageurl** に設定されています。
**レスポンス：**
```json theme={null}
{
"results": [
{
"rows": [
{
"id": "123",
"name": "Acme",
"country": "United States",
"no_employees": 500
}
],
"nextpageurl": "https://myapi?nextpage=81a3ebdb-1483-45cd-84d1-f711d1308698"
}
]
}
```
{cloudEnv && (
<>
Edit the RSD Script
In {siteNameShort}, you can directly edit the RSD script for an API connector table from the UI. An RSD script is a schema definition that controls how {siteNameShort} represents API response data as a table. Editing this script allows you to override the automatic table configuration and define exactly how columns map to elements in the API response.
This capability is useful when the standard table builder cannot correctly map response values to columns, particularly for complex XML structures.
When to Edit the RSD Script
The standard table configuration in the UI uses repeat elements to map API responses into rows and columns. This approach works for most JSON and XML responses where each row contains both column names and values in a consistent structure.
However, some APIs return XML where column names and data values are separated into different sections. For example, column names might appear in a <header> element while row data appears in a <body> element. In this structure, the repeat-element configuration cannot associate header labels with the corresponding data values.
In these cases, editing the RSD script allows you to manually define the column-to-data mapping by using XPath expressions.
How to Map Columns with XPath
In the RSD script, each column is defined as an <attr> element. This element specifies the column name, data type, and the XPath expression that identifies the corresponding value in the API response.
To define a column:
- Set the name attribute to the column name that should appear in the output table.
- Set the
xs:type= attribute to the appropriate data type (for example, "string").
- Set the
other:xPath= attribute to an XPath expression that points to the column value within each row.
You must also define the row-level XPath by setting the XPath attribute in the RSD script to the element that represents each row.
Consider the XML response in the following example:
{`
Derek
Doe
`}
In this structure, the column labels are defined in the <header> section, while the row data is defined in the <body> section.
To map this data in the RSD script, define the row-level XPath as follows: /result/body/row
Then define the columns as shown here:
{`
`}
The positional index (col[1], col[2], and so on) corresponds to the order of the columns that is defined in the header. This approach enables you to map each column name to the correct value in the row data.
)}