Dataphin:API データソースの作成

主な機能

以下の表は、API データソースの主な機能をまとめています。各パラメーターの詳細な構成については、以降のセクションをご参照ください。

API 認証方式

本セクションでは、サポートされている API 認証方式、その主要なパラメーター、および使用ガイドラインについて説明します。

要約すると、Basic 認証および Alibaba Cloud AppKey 認証は特定のシナリオに適しています。API キー認証および Bearer トークン認証は汎用的です。OAuth 2.0 は複雑な承認シナリオに最適であり、「なし」オプションはパブリック API に適しています。

• なし（認証なし）

  • 概要

    この方式では、認証資格情報を使用せずに API 呼び出しを行うことができます。パブリックなエンドポイント（例：パブリッククエリサービス）や、IP アローリストや内部ビジネスロジックなどの他のセキュリティ対策に基づいてアクセス制御を行う API に適しています。

  • 構成

    認証パラメーターは不要です。API を直接呼び出すことができます。

• Basic 認証（Basic Auth）

  • 概要

    これは、標準 HTTP 認証フレームワークに基づくシンプルな認証方式です。ユーザー名とパスワードを組み合わせ、Base64 エンコードしてリクエストヘッダーに含めます（Authorization: Basic <encoded_string>）。資格情報を平文で露出させないために、HTTPS 上でのみこの方式を使用することを推奨します。

  • 必須パラメーター

    パラメーター	説明	例
    ユーザー名	API プロバイダーが Basic 認証用に提供するユーザー名です。通常、英数字および特殊文字をサポートする文字列です。	api_user_01
    パスワード	API プロバイダーが提供するパスワードです。対応するユーザー名とともに使用する必要があります。	e89s76d9@2026

• Alibaba Cloud AppKey 認証

  • 概要

    Alibaba Cloud オープンプラットフォームの標準認証方式であり、AppKey および AppSecret を用いてリクエストを検証します。署名ルールは Alibaba Cloud プロダクトによって若干異なりますが、一般的にはリクエストパラメーター、タイムスタンプ、その他の値を暗号化します。署名計算の詳細については、「API コンポーネントによるオフライン統合」をご参照ください。この方式は、Object Storage Service (OSS)、ApsaraDB RDS、Short Message Service (SMS) などのさまざまな Alibaba Cloud オープン API を呼び出す際に最適です。

  • 必須パラメーター

    パラメーター	説明	例
    AppKey	API プロバイダーが割り当てる AppKey で、アプリケーションの固有識別子として機能します。	api_user_01
    AppSecret	API プロバイダーが割り当てるシークレットキーです。対応する AppKey とともに使用する必要があります。	e89s76d9@2026

• API キー認証

  • 概要

    この方式では、カスタムのキーと値のペアを使用して認証を行います。キーはリクエストパラメーター（URL）、リクエストヘッダー、またはリクエストボディのいずれかに送信できます。これは、ほとんどの社内、カスタム構築、およびサードパーティの API と互換性のある非常に柔軟な方式です。

  • 必須パラメーター

    パラメーター	説明	例
    キー	API プロバイダーが定義した認証キーの名前です。例：api-key、app-key、token-id。	api_key
    値	キーに関連付けられたシークレット値です。この値は API プロバイダーが提供し、機密として保持する必要があります。	789d87s6a987d6s9876d987s6987d
    追加	キーと値のペアをリクエストのどこに配置するかを指定します。オプションは以下の通りです： パラメーター：キーをクエリパラメーターとして URL に追加します。例：https://api.example.com?api_key=789d87s6...。 ヘッダー：キーをリクエストヘッダーに含めます。例：api_key: 789d87s6...。 ボディ：キーを POST リクエストボディに含めます。	ヘッダー

• Bearer トークン認証

  • 概要

    これは、HTTP Bearer トークンに基づくシンプルな認証方式です。トークンはリクエストヘッダーに直接送信されます（Authorization: Bearer <token_value>）。一時的なアクセストークンなど、単一使用または短期間有効なトークンを必要とするシナリオに適しています。

  • 必須パラメーター

    パラメーター	説明	例
    トークン	API プロバイダーが発行する Bearer トークンです。通常、JSON Web トークン（JWT）やランダム文字列などの文字列です。トークンが有効で期限切れでないことを確認してください。	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• OAuth 2.0（認証コード付与）

  • 概要

    業界標準の承認プロトコルである OAuth 2.0 では、API 呼び出しの前にアクセストークンを取得する必要があります。これは、ユーザーアウソリゼーションやマルチクライアントアクセスを必要とするシナリオ（例：サードパーティプラットフォームとの統合）に最適です。

    たとえば、オフライン統合タスクでは、Dataphin がターゲット API への各リクエストの前に新しいアクセストークンを取得し、その新しいトークンでリクエストを行います。

  • 必須パラメーター

    	パラメーター	説明	例
    基本構成	トークンプレフィックス	リクエストヘッダー内のトークンのプレフィックスです。一般的な値は Bearer、Token、OAuth です。	Bearer
    	アクセストークンパス	API 応答内のアクセストークン値の JSONPath です。たとえば、応答が以下のようになっている場合： { "access_token": "access_token_return", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "d68297697d37d97197d7a0c986f9d77989118912" } access_token を入力します。	access_token
    アクセストークン取得構成	リクエストメソッド	トークンを取得するための HTTP メソッドです。GET および POST をサポートしています。ほとんどのサービスでは POST を使用します。	POST
    	トークン URL	アクセストークンを取得するためのサーバーが提供する API エンドポイントです。	https://oauth.example.com/token
    	クライアント ID	API プロバイダーが提供するアプリケーションの固有識別子です。	client_123456789
    	クライアントシークレット	API プロバイダーが提供するアプリケーションのシークレットキーです。このキーは機密として保持する必要があります。	secret_987654321
    	クライアント認証（任意）	クライアント ID およびクライアントシークレットを送信する方法を指定します。オプションは以下の通りです： リクエストヘッダー：Basic 認証形式で Authorization ヘッダーに資格情報を送信します。 リクエストボディ：トークン要求のボディにパラメーターとして資格情報を送信します。	リクエストヘッダー
    	トークン取得のための追加リクエストパラメーター（任意）	トークンを取得するために必要な追加パラメーターを指定します。これらは URL パラメーターまたはヘッダーとして送信できます。例：grant_type=client_credentials や scope=read_write。	パラメーター：grant_type=client_credentials

API の要件

• データ読み取り API

  データ読み取り API の応答は、単一のレコード内のすべてのフィールドがスカラー値である JSON オブジェクトである必要があります。フィールドに配列を含めることはできません。

  • サポートされるデータ構造（準拠）

    単一のレコード内のすべてのフィールド（ネストされたオブジェクト内のフィールドを含む）は、文字列、数値、ブール値などのプリミティブ型でなければなりません。

    // ページネーション対応 API の応答には、page_no や page_size などのページネーション情報が含まれている必要があります。
    {
      "code": 200,          
      "msg": "リクエスト成功",     
      "request_id": "req-20260228001", // トラブルシューティングのための固有リクエスト ID。
      "data": [{
        "user_id": 10001,
        "user_name": "田中一郎",
        "user_phone": "03-1234-5678",
        "user_email": "ichiro.tanaka@example.co.jp",
        "user_hobbies": {
          "sports" : "バドミントン、卓球",// マルチレベルのネストされたオブジェクトはサポートされています。
          "instrument" : "ギター"
        },
        "create_time": "2026-02-28 10:00:00"
      },{
        "user_id": 10002,
        "user_name": "佐藤次郎",
        "user_phone": "03-1234-5679",
        "user_email": "jiro.sato@example.co.jp",
        "user_hobbies": {
          "sports" : "バスケットボール",
          "instrument" : "ピアノ、二胡"
        },
        "create_time": "2026-02-28 10:00:00"
      }],
      "page_no": 1,     // 現在のページ番号。ページネーション対応 API では必須です。
      "page_size": 10,  // 1 ページあたりのアイテム数。ページネーション対応 API では必須です。
      "total": 23,      // アイテムの総数。任意です。
      "pages": 3        // 総ページ数。任意です。
    }

  • 非サポートのデータ構造（非準拠）

    単一のレコード内のフィールド（ネストされたオブジェクト内のフィールドを含む）は、配列を含めることができません。以下の構造は非準拠であり、解析できません。

    {
      "code": 200,          
      "msg": "リクエスト成功",     
      "request_id": "req-20260228001", 
      "data": [{
        "user_id": 10001,
        "user_name": "Zhang San",
        "user_phone": "13800138000",
        "user_email": "zhangsan@example.com",
        "user_hobbies": {
          "sports": ["Basketball"],          // 禁止: フィールド値は配列です。
          "instrument": ["Piano", "Erhu"] // 禁止: フィールド値は配列です。
        },
        "create_time": "2026-02-28 10:00:00"
      }]
    }

• データ書き込み API

  データ書き込み API は、フィールド値がスカラー型であるリクエストボディを受け入れる必要があります。ネストされたオブジェクトおよび配列値はサポートされていません。

  • サポートされるデータ構造（準拠）

    単一のレコード内のすべてのフィールド値は、文字列、数値、ブール値などのプリミティブ型でなければなりません。ネストされたオブジェクトおよび配列はサポートされていません。

    [{
        "user_id": 10001,
        "user_name": "Zhang San",
        "user_phone": "13800138000",
        "user_email": "zhangsan@example.com",
        "create_time": "2026-02-28 10:00:00"
      },{
        "user_id": 10002,
        "user_name": "Li Si",
        "user_phone": "13800138001",
        "user_email": "lisi@example.com",
        "create_time": "2026-02-28 10:00:00"
    }]

  • 非サポートのデータ構造（非準拠）

    単一のレコード内の任意のフィールドの値は、ネストされたオブジェクトまたは配列であってはなりません。以下の構造は要件を満たさず、解析できません。

    [{
        "user_id": 10001,
        "user_name": "Zhang San",
        "user_hobbies": ["Basketball", "Piano"], // 禁止: 配列型。
        "user_info": {                           // 禁止: ネストされたオブジェクト型。
          "phone": "13800138001",
          "email": "zhangsan@example.com"
        },
        "create_time": "2026-02-28 10:00:00"
      },{
        "user_id": 10002,
        "user_name": "Li Si",
        "user_hobbies": ["Basketball", "Piano"], // 禁止: 配列型。
        "user_info": {                           // 禁止: ネストされたオブジェクト型。
          "phone": "13800138002",
          "email": "lisi@example.com"
        },
        "create_time": "2026-02-28 10:00:00"
    }]

API コンポーネントによるオフライン統合

API データソースの主なユースケースの一つがオフライン統合です。入力および出力のシナリオにおける機能および要件はわずかに異なります。API 入力および出力コンポーネントの構成方法については、以下のトピックをご参照ください：

• API 入力コンポーネントの設定

• API 出力コンポーネントの設定

署名認証

署名認証は、リクエストパラメーター、タイムスタンプ、乱数（nonce）、シークレットキーなどの重要なリクエスト情報をハッシュ関数で処理して署名文字列を生成することで、堅牢な本人確認を提供します。サーバーは同じルールで署名を再計算し、受信した署名と比較することで、リクエストの改ざんおよびリプレイ攻撃を防止します。この方式は、他の認証方式と併用することも、単独で使用することもでき、API のセキュリティを強化できます。API プロバイダーが署名認証を要求する場合は、本セクションをご参照ください。

必須パラメーター

以下のパラメーターは、署名文字列の生成に使用されます。

データ読み取り（API 入力コンポーネント）

必須パラメーター

複数（反復）リクエスト：ページネーションループ

単一のリクエストで全データを返さない API（ページネーション対応 API やスクロール API など）では、自動ループ呼び出し 機能を使用して、終了条件が満たされるまで継続的にリクエストを行い、すべてのデータを集約できます。この機能は ページ番号／オフセットループ および カーソルループ の 2 つのモードをサポートしており、終了条件が満たされるまで継続的にリクエストを行います。これにより、すべてのデータが自動的に集約され、さまざまなバッチデータ取得シナリオに適しています。

• ページ番号／オフセットループ

  ページ番号（Page Number）およびページサイズ（page size）またはオフセット（Offset）および制限（limit）を入力パラメーターとして受け入れる標準的なページネーション対応 API にこのモードを使用します。これにより、特定のページのデータ（例：page=1&size=100 や offset=0&limit=100）が返されます。

  パラメーター	説明	例（ページ番号とページサイズ）	例（オフセットと制限）
  リクエストパラメーター	ループ入力パラメーターの配置場所（パラメーターまたはボディのみ）および名前を選択します。	配置場所：パラメーター パラメーター名：page	配置場所：パラメーター パラメーター名：offset
  初期値	ループパラメーターの初期値です。	1（ページ番号は 1 から開始）	0（オフセットは 0 から開始）
  手順	各ループ後のパラメーターの増分です。この値は 1 ページあたりのアイテム数と一致する必要があります。	1（1 ページあたり 100 アイテムの場合、ページ番号は 1 ずつ増加）	100（1 ページあたり 100 アイテム。オフセットは各リクエストごとに 100 ずつ増加）
  終了条件	ループを停止するルールです。 応答パラメーター、リクエストパラメーター、定数、またはリクエスト数を比較できます。	ルール：応答パラメーター current_page = 定数 10 （10 ページ取得後に停止。この条件は柔軟です。）	ルール：応答パラメーター has_more = 定数 false （データがなくなるときに停止。この条件は柔軟です。）

• カーソルループ

  このモードは、高同時実行数または大量データを扱う API に最適です。現在の応答から得られる Cursor 値を次のリクエストの入力として使用することで、ページ番号によるページネーションでよく見られる「データの欠落または重複」の問題を回避できます。

  パラメーター	説明	例
  リクエストパラメーター	カーソルパラメーターの配置場所（パラメーターまたはボディ）および名前を選択します。	配置場所：パラメーター パラメーター名：next_cursor
  カーソルパラメーター	次のリクエストのカーソル値のソース を定義します。値は現在のリクエストの応答から抽出されます。JSONPath がサポートされています。	応答パラメーター + data.next_cursor
  初期値	最初のリクエストの初期カーソル値で、API で定義されています。デフォルト値は 0 です。	0
  終了条件	ループを停止するルールです。 一般的な条件には、応答からのカーソル値が定数（空文字列や 0 など）であるかどうか、または応答データが空かどうかを確認することが含まれます。	ルール：応答パラメーター data.next_cursor = 定数 ""（空文字列）

複数（反復）リクエスト：パラメーター走査ループ

このモードでは、固定のパラメーター値のリストを反復処理します。各リクエストでは、リスト内の 1 つの値が API の指定された入力パラメーターに渡されます。リスト内のすべての値が使用されるまでループが続きます。これは、都市、部門、製品 ID などの固定ディメンションに基づいてデータを照会する必要があるシナリオに適しています。パラメーターのリストを提供する方法として、手動入力 および API 経由での取得 の 2 つがサポートされています。

データ書き込み（API 出力コンポーネント）