Version 24.2.9064

• API コネクタを追加
• API への認証
  • None
  • Basic
  • Digest
  • Bearer Token
  • OAuth
  • OAuthPassword
  • OAuthClient
• 接続を完了する
• ヘッダーを追加
• テーブルを追加
• 疑似カラムを追加
• フィルタを追加
  • フィルタの作成
  • 行ごとのリクエスト機能を使用したデータのフィルタリング
• ページネーションを追加
  • Offset
  • Number
  • Token
  • URL

CData Sync API コネクタは、API に直接接続する簡単で完全にカスタマイズ可能な方法を提供します。接続を確立したら、組み込みのウィザードを使用して、後でジョブで使用できるテーブル形式でAPI レスポンスデータを構成します。

API コネクタを追加

Sync でAPI のデータを使用できるようにするには、まず以下の手順でコネクタを追加する必要があります。

1. Sync のダッシュボードから接続ページを開きます。

2. 接続を追加をクリックしてコネクタを選択ページを開きます。

3. データソースタブをクリックしてAPI 行に移動します。

4. 行末にある接続を設定アイコンをクリックして、新しい接続ページを開きます。接続を設定アイコンが利用できない場合は、コネクタをダウンロードアイコンをクリックしてAPI コネクタをインストールします。新規コネクタのインストールについて詳しくは、接続を参照してください。

API への認証

コネクタを追加したら、必須プロパティを設定する必要があります。

新しい接続ページで任意の接続名を入力します。

CData Sync は、いくつかの方法でAPI への認証をサポートしています。以下から認証方法を選択し、認証の詳細を含む該当セクションに進みます。

• None
• Basic
• Digest
• Bearer Token
• OAuth
• OAuthPassword
• OAuthClient

None

認証なしで接続するには、Auth Scheme で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 を入力。

  Note：OAuth 1.0 では、認可されたリクエストトークンはアクセストークンと交換されます。

• OAuth Refresh Token URL - アクセストークンの有効期限が切れたときにリフレッシュトークンが新しいアクセストークンと交換されるURL を入力。

  Note：データソースによっては、このURL はアクセストークンURL と同じである可能性があります。

• Scope（オプション）- 最初のアクセストークンとリフレッシュトークンを取得するために必要なスコープを入力。

OAuthPassword

OAuth カスタムクレデンシャルで接続するには、次のプロパティを指定します。

• Auth Scheme - OAuthPassword を選択。

• User - API アカウントへの認証に使用するユーザー名を入力。

• Password - API アカウントへの認証に使用するパスワードを入力。

• OAuth Client Id - OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントId を入力。

• OAuth Client Secret - OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントシークレットを入力。

• OAuth Access Token URL - アクセストークンのリクエストを行うURL を入力。

  Note：OAuth 1.0 では、認可されたリクエストトークンはアクセストークンと交換されます。

• OAuth Refresh Token URL（オプション）- アクセストークンの有効期限が切れたときにリフレッシュトークンが新しいアクセストークンと交換されるURL を入力。

  Note：データソースによっては、このURL はアクセストークンURL と同じである可能性があります。

  • Scope（オプション）- 最初のアクセストークンとリフレッシュトークンを取得するために必要なスコープを入力。

OAuthClient

OAuth カスタムクレデンシャルで接続するには、次のプロパティを指定します。

• Auth Scheme - OAuthClient を選択。

• OAuth Client Id - OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントId を入力。

• OAuth Client Secret - OAuth 認証サーバーにアプリケーションを登録した際に割り当てられたクライアントシークレットを入力。

• OAuth Access Token URL - アクセストークンのリクエストを行うURL を入力。

  Note：OAuth 1.0 では、認可されたリクエストトークンはアクセストークンと交換されます。

• OAuth Refresh Token URL（オプション）- アクセストークンの有効期限が切れたときにリフレッシュトークンが新しいアクセストークンと交換されるURL を入力。

  Note：データソースによっては、このURL はアクセストークンURL と同じである可能性があります。

• Scope（オプション）- 最初のアクセストークンとリフレッシュトークンを取得するために必要なスコープを入力。

接続を完了する

接続を完了するには：

1. Test URL に認証スキームを検証するためのURL を入力します。

2. 接続および作成するテーブルの両方に適用されるグローバルヘッダーを定義します。詳しい手順については、ヘッダーを追加を参照してください。

3. 必要に応じて、Other プロパティ（Miscellaneous セクションの下）で追加の設定を行います。このプロパティは、通常の使用および機能には必要ありません。ただし、必要な場合は、接続に必要な追加設定のリストをセミコロンで区切って入力してください。

4. 高度な設定タブで接続の高度な設定を定義します。（ただし、ほとんどの場合これらの設定は必要ありません。）

5. OAuth で認証する場合は、API への接続 をクリックしてAPI アカウントに接続します。

6. 作成およびテストをクリックして接続を作成します。

接続の作成に成功したら、次のセクションで説明するように、テーブル、疑似カラム、フィルタ、およびページネーションを追加できます。

• テーブルを追加
• 疑似カラムを追加
• フィルタを追加
• ページネーションを追加

ヘッダーを追加

接続ページのヘッダーを追加セクションでは、接続および作成するテーブルの両方に適用されるグローバルヘッダーを定義できます。

すべてのAPI コールで送信されるHTTP ヘッダーを追加するには、次のプロパティを指定します。

• Name - 名前フィールドにヘッダー名を入力（例：Token）。

• Value - ヘッダーの値を入力（例：トークン）。

さらにヘッダーを追加する場合は、ヘッダーを追加をクリックしてヘッダー名と値を指定します。

テーブルを追加

API に接続すると、テーブル形式でAPI データを作成、表示、設定できます。

テーブルを作成するには：

1. API 接続を開いてテーブルタブをクリックし、新規テーブルページを開きます。

2. テーブルを追加をクリックして、新規テーブルの作成を開始します。

3. リクエストURL セクションで：

   1. リクエストURL リストから、リクエストする方法（GET またはPOST）を選択します。

   2. 次の例に示すように、選択したメソッドの右側にある空白フィールドにAPI エンドポイントのURL を入力します。

      

      Note：メソッドに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 レスポンスの要素のパスです。Sync は検出された各配列をレスポンスデータで返すので、複数のパスを選択することができます。この例では、source が繰り返し要素です。

   

   Sync は可能な繰り返し要素をインテリジェントに判断しようとしますが、特定のシナリオでは検出することができません。そのような場合は、次のようにカスタム繰り返し要素パスを設定する必要があります。

   1. カスタム繰り返し要素を使用（ダイアログボックスの右上隅）をクリックします。

   2. 繰り返し要素を追加をクリックします。

   3. 繰り返したい要素のパスを入力します。

10. 次へをクリックします。

11. 含める特定のカラムを選択します。

    

    すべてのカラムを含めるには、カラムリストの右上にあるすべて選択をクリックします。

12. 次へをクリックします。これにより、ダイアログボックスにテーブルをプレビュータブが開き、選択したカラムを含むテーブルが表示されます。

13. テーブル名フィールドにテーブルの名前を入力します。

    

14. Confirm をクリックし、テーブルの選択内容を保存します。

15. 保存（新規テーブルページの右上隅）をクリックして、API コネクタページ上のテーブルへのリンクを保存します。

    

疑似カラムを追加

疑似カラムはテーブルカラムの動作を模倣しますが、疑似カラムはソーステーブルやAPI に物理的に格納されません。これらのカラムを使用すると、API に（SQL WHERE 句経由で）送信されるリクエストを変更できますが、その値は同期先テーブルには複製されません。

Sync で疑似カラムを作成するには：

1. API コネクタからテーブル > タスクを選択します。

2. タスクページ下部のテーブル詳細セクションに移動し、疑似カラムタブをクリックします。

3. 疑似カラムを追加をクリックします。

   

4. カラム名テキストボックスに、疑似カラムの名前を入力します。次に、データ型リストから適切なデータ型を選択します。

   

   上の画像で示すように、アウトプットチェックボックスをON にすることで、API テーブルの結果内に擬似カラムを出力することを選択できます。さらに、タスクのWHERE 句に疑似カラムを含めることを必須にしたい場合は、必須チェックボックスをON にします。タスクがWHERE 句に疑似カラムを含めない場合、Sync は次の例のようなエラーメッセージを生成します。

   

   疑似カラムを削除するには、疑似カラム行の最後にある削除アイコンをクリックします。

5. 保存をクリックします。

フィルタを追加

カラムを持つテーブルを作成したら、クエリ中にWHERE 句が発行されたときのAPI コネクタの動作を定義するフィルタを作成できます。フィルタは、フィルタリング処理をサーバー側のAPI に委任することでパフォーマンスを向上させます。フィルタを含めない場合、クエリオプションは代わりにSync によって処理されます。

フィルタの作成

テーブルの各カラムにフィルタを作成できます。

フィルタを作成するには：

1. 以下で示すように、新規テーブルページにあるフィルタタブをクリックします。

   

2. カラムリストの下にあるフィルタを追加をクリックします。

3. フィルタしたいカラムをカラムリストから選択します。

4. Operator リストから条件を選択します。次のオプションから選択可能です。

   • 次と等しい

   • 次と等しくない

   • 次より小さい

   • 次より小さいか等しい

   • 次より大きい

   • 次より大きいか等しい

5. Type リストから種類（パラメータまたはヘッダー）を選択します。次に、カラム名と一致しない場合はパラメータ名またはヘッダー名を入力します。

6. 保存（ページ右上）をクリックしてフィルタを保存します。

次の例は、Reports テーブル内のレコードをレコードの作成日でフィルタリングするクエリを処理するフィルタを作成する方法を示しています。

クエリ例

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 パラメータを含めるよう接続に指示します。

行ごとのリクエスト機能を使用したデータのフィルタリング

Sync アプリケーションでは、行ごとのリクエスト機能を使用してデータをサブセット化できるようになりました。行ごとのリクエストにより、SQL IN 句を使ってSync がフィルタ値ごとに個別のリクエストを渡すことができます。この機能は、子データセットをクエリする際に、そのクエリが親データセットの識別子（Id）が必要な場合に便利です。例えば、請求書データセット（親）から、ラインアイテム（子）を別々の行として1つの同期先テーブルに分割したいとします。次のクエリは、請求書Ｉｄ 値に対する個別のリクエストを動的に渡します：

REPLICATE [InvoiceLineItems] SELECT * FROM [InvoiceLineItems] WHERE InvoiceID IN ('1', '2', '3')`

さらに、フィルタ内でInner SELECT クエリを使用して請求書Id の動的リストを渡すことができます：

REPLICATE [InvoiceLineItems] SELECT * FROM [InvoiceLineItems] WHERE InvoiceID IN (SELECT Id FROM [Invoices])

行ごとのリクエスト機能を有効にするには：

1. リクエストURL を変更して、中かっこ内に一意のレコード識別子カラムの名前を含めます。中かっこ内にカラム名を追加すると、リクエストURLテキストボックス右端の上に行ごとのリクエストが検出されましたが表示されます。

2. テーブルを設定をクリックします。

3. 一意のレコード識別子カラムのサンプル値を入力します。

4. “テーブルを追加”セクションの手順7-13に従います。

   Note：一意のレコード識別子カラム（大文字小文字を区別）と一致するカラムまたは疑似カラムが存在することを確認してください。一致しない場合、Sync は警告を表示します。

5. 保存（新規テーブルページの右上）をクリックします。

ページネーションを追加

Sync は、複数の種類のページング実装をサポートしています。ページネーションタイプを追加するには：

1. ページネーションタブをクリックします。

2. Type リストからページネーションの種類を選択します。次の種類から選択可能です：

   • None - API リクエストが1つのレスポンスで完全なデータセットを返す場合は、このタイプを選択。

   • Offset - API リクエストがページング用のレコードオフセットパラメータを提供する場合は、このタイプを選択。詳しくは、Offset タイプを参照してください。

   • Number - API リクエストに現在のページ番号を指定するパラメータが含まれている場合は、このタイプを選択。詳しくは、Number タイプを参照してください。

   • Token - API レスポンスに次のページ用のトークンが含まれている場合は、このタイプを選択。詳しくは、Token タイプを参照してください。

   • URL - API レスポンスに次のページ用の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 - Sync がページングトークンを設定するリクエストボディのパスを入力。

  • URL Parameter - Sync がページングトークンに渡すURL パラメータの名前を入力。

URL パラメータの使用例

次のリクエストでは、URL Parameter はpageToken に、Token Path は /results/nextpagetoken に設定されています。

リクエスト：https://myapi?pageToken=123456

レスポンス：

```
{
   "results": [
     {
        "rows": [
          {
             "id": "123",
             "name": "Acme",
             "country": "United States",
             "no_employees": 500
          },
          . . .*more code lines*. . .
         ],
         "nextpagetoken": 123457
       }
   ]
}
```

<a name=”request-path-example></a>リクエストパスの使用例

次のリクエストでは、Request Path は /request/pageToken に、Token Path は /results/nextpagetoken に、Has More Path は /results/morePages に設定されています。

リクエストボディ

  {
    "request": [
      {
        "country": "United States",
        "pageToken": 123456
      }
    ]
  }

レスポンス

  {
    "results": [
      {
        "rows": [
          {
             "id": "123",
             "name": "Acme",
             "country": "United States",
             "no_employees": 500
          },
          . . .*more code lines*. . .
         ],
         "nextpagetoken": 123457,
         "morePages": true
       }
    ]
  }

URL

URL を選択した場合は、URL ソースも選択する必要があります。

• Header Name - 次ページURL がリンクヘッダーとともにレスポンスヘッダーに渡される場合は、ヘッダー名を入力。

• Request Path - 次ページURL を定義するAPI レスポンスのパスを入力。この値はXPath 記法で指定する必要があります。次の例を参照してください。

リクエストパスの使用例

次の例では、Request Path は /results/nextpageurl に設定されています。

レスポンス：

{
  "results": [
    {
      "rows": [
        {
          "id": "123",
          "name": "Acme",
          "country": "United States",
          "no_employees": 500
        },
        ...
      ],
      "nextpageurl": "https://myapi?nextpage=81a3ebdb-1483-45cd-84d1-f711d1308698"
    }
  ]
}