Data Prep用のREST APIコネクター¶

ユーザーペルソナ：Data Prepユーザー、Data Prep管理者、またはデータソース管理者

Data Prepの設定¶

このコネクターを使用すると、REST API に接続して、REST リソースをインポートできます。コネクタの作成に使用されるパラメーターに関する情報を以下に示します。

一般¶

• 名前： UIでユーザーに表示されるデータソースの名前。

• 説明：UIでユーザーに表示されるデータソースの説明。

Webプロキシ¶

プロキシサーバーを介してREST APIソースに接続する場合、これらのフィールドはプロキシの詳細を定義します。

• Webプロキシ：プロキシが不要な場合は [なし]、プロキシサーバー経由でMarketo RESTエンドポイントに接続する必要がある場合は [プロキシ] を選択します。Webプロキシサーバーが必要な場合、プロキシ接続を有効にするには以下のフィールドが必要です。

• プロキシホスト：Webプロキシサーバーのホスト名またはIPアドレス。

• プロキシポート：データソースのプロキシサーバー上のポート。

• プロキシユーザー名：プロキシサーバーのユーザー名。

• プロキシパスワード：プロキシサーバーのパスワード。

  *認証されていないプロキシ接続の場合は、ユーザー名とパスワードを空欄にしてください。

REST API設定¶

このセクションでは、REST APIリソースを見つけるために使用される情報を提供します。

これを設定する方法の例については、RESTAPI認証設定を参照してください。

• ベースURL：REST APIのベースURL。ベース URL にはプロトコル（http/https）、ホスト名（ポート番号はオプション）、コンテキスト パスを含める必要があります。
  • 例： http(s)://api.domain.com(:port)/rest/v1

• リソース：インポートする複数のRESTリソース。各行には、単一のRESTリソース設定を、name:path?queryの形式で含めます。

  • nameはインポートするリソースのユーザーに表示される名前であり、RESTリソース設定に必要です。この名前は、「Browse」のユーザーインターフェースで表示されます。アカウントの詳細。

  • pathはリソースへのパスであり、RESTリソース設定に必要です。このパスはスラッシュ(/)で始まり、オプションで複数のセグメントをスラッシュ(/)で区切ります。例：/resource/sub-category

  • queryは、リソースの取得時に使用するオプションのフィルタリング基準であり、RESTリソース設定ではオプションです。クエリー構文は、「&」で区切られたキー=値のペアである必要があります。例： criteria=active&order=descまたはjql=status=done。

REST API認証の設定¶

このセクションでは、REST API サービスエンドポイントへの認証に使用する情報を指定します。

• 認証タイプ：要件に基づいて、オプションの1つを選択します。

• 認証なし：REST APIが認証を必要としない場合

• 基本認証：REST APIがユーザー名とパスワードによる認証を許可する場合

• ベアラートークン：REST APIがベアラートークンによる認証を許可する場合ベアラートークンの場合、各Webサービスはトークンへのアクセスまたはトークンの生成を異なる方法で提供する可能性があり、Webサービスのドキュメントでその検索方法を説明する必要があります。

• ユーザー名およびパスワード：[基本認証] に [認証タイプ] を選択した場合、これらのフィールドは認証用に提供されます。一部のWebサービスではどちらか一方のフィールドのみが必要です。そのため、ほとんどの場合、両方のフィールドが必要になりますが、設定ページでは両方を空白にすることができます。これにより、データソースへの認証中にエラーが発生する可能性がありますが、データソースの保存時にフォーム検証エラーは発生しません。

• ベアラートークン：[認証タイプ] に [ベアラートークン] を選択した場合、これを認証用に提供する必要があります。すべてのシステムがこれを異なる方法で処理するため、ユーザーはこのトークンを取得する方法を知っている必要があります。このトークンを取得するには、管理者の助けが必要になる場合もあります。

REST APIのテスト接続と運用の設定¶

• テスト接続と運用の方法：Data PrepコネクターがREST APIサービスに接続できるかどうか、また、コネクタがリソースを要求する際にどのメソッドを使用するかを判断するために、リクエストで使用されるHTTP方法。POST自動」を選択すると、1、2、3の接続テストを行いますので、どの方法を選択してよいかわからない場合には最適な方法です。HEAD``GET

• GET``HEAD``GET選択された方法は、実際のインポートにも使用され、1または2がテストに成功した場合は3が、4が成功した場合は5がインポートに使用されることになります。POST``POST

• 接続タイムアウト：REST APIに接続するためのタイムアウト（ミリ秒）。

データインポート情報¶

ブラウジング経由¶

リソースリストで定義されたリソース名を使用して、インポートワークフロー内のリソースをインポート可能なデータセットとして表示します。

SQLクエリー経由¶

サポートされていません。

技術的な仕様¶

ページ付け¶

• このコネクターは、RESTデータセットのRFC 5988ページ付けをサポートしています：https：//tools.ietf.org/html/rfc5988

• ページ付けされたREST応答の場合、ページ付けされた各応答には、結果の次のページのURLを識別するHTTPヘッダーが含まれます。

• ページ付けされたデータセットが要求されると、RESTコネクターはデータセットがページ付けされていることを自動的に識別し、データリンクをたどります。

  • データの次のページのHTTPリンクを自動的に抽出します。

  • 結果の現在のページから結果を返します。

  • 呼び出しを実行して、結果の次のページを取得します。

• Data Prep UIを使用したインポート中は、プレビューの迅速な表示を可能にし、レート制限されたAPIに対するヒットを減らすために、1ページのデータ値のみを表示します。

• インポート中に、コネクターは次のことを行います。

  • データの次のページのHTTPリンクを自動的に抽出する。

  • 結果の現在のページから結果を返す。

  • 呼び出しを実行して、結果の次のページを取得します。

パフォーマンス¶

RESTコネクターのパフォーマンスは、利用するREST APIの実装に大きく依存します。

• REST APIの呼び出しごとにデータセット全体を返すことをサポートするREST APIで最高のパフォーマンスが得られます。これは、チャンク転送エンコーディングを利用するAPIの典型です。このシナリオでは、RESTコネクターは単一のAPI呼び出しを実行して完全なデータセットを取得します。

• ページ付けを利用するREST APIは、追加のREST API呼び出しが必要になるため、パフォーマンスが低下します。

  • ページ付けスタイル：RFC 5899

  • 各応答には、N個のレコードと、次のバッチを指すURLを含むHTTPヘッダーが含まれます。

• REST APIドキュメントを確認して、API呼び出しの数を減らすために設定できるMaximum（最大）ページサイズを特定します。

• 例：GitHub REST API

• APIにはレート制限がある場合があります。ページ分割された大規模なデータセットをインポートする場合、時間枠内に実行されるREST呼び出しの数に制限がかかることは珍しくありません。たとえば、GitHubでは1時間あたり5000件のリクエストが許可され、Googleドライブでは100秒あたり1000件のリクエストが許可されます。

FAQ／トラブルシューティング／一般的な問題¶

OAuth認証はサポートされていますか？¶

現時点ではサポートされていません。現在、ユーザー名/パスワードおよびトークン認証方法のみがサポートされています。多くのデータソースはOAuth認証のみを許可しており、これらのソースは現時点ではサポートされていません。この理由でDataSourceに接続できない場合は、Data Prep Client Successに連絡してください。

「テスト接続」メッセージは何を意味しますか？¶

• テスト接続は、リソースリストの各エントリが期待される形式と一致することを確認します。

• エントリーが期待される形式と一致しない場合、識別された形式の問題とエントリー番号を示すエラーが発生します。

  

• 各リソースエントリーにユニーク数のデータセット名を使用しないと、形式の検証に失敗します。

  

• テストによってリソースの適切な形式が確認された後、リソースリストの最初のエントリのみが、接続が正しく設定されていることを確認するために使用されます。

設定例¶

以下は、REST APIコネクターの実際の使用例です。アカウントでこれらのいずれかを自由に使用してください。ただし、企業はAPIを随時、場合によっては通知なしに変更する可能性があり、これらは完全にサポートされているデータソースではないことにご注意ください。これは、Data Prepがこれらの設定で発生する可能性のある問題のトラブルシューティングを支援できず、それらが時代遅れになる可能性があることを意味します。

簡単な学習例¶

Web上には、学習、テスト、およびプロトタイピングを目的として作成された、単純で認証されていないREST APIリソースが数多くあります。これらのソースの1つはJSONPlaceholderです。この例は単純化しすぎている可能性がありますが、REST APIコネクターを使用してRESTful Webサービスに接続する方法の構成要素を示すことを目的としています。

データセットが小さいため、レート制限は投稿されず、ページ付けもありません。

設定¶

• ベースURL：https://jsonplaceholder.typicode.com

• リソース：

• 投稿：/投稿

• コメント：/コメント

• アルバム：/アルバム

• 認証：認証なし

• REST APIテスト設定：自動化

[データソースのテスト]をクリックしてセットアップが機能していることを確認し、[保存]をクリックした後、このデータソースを使用してデータをData Prepにインポートできます。

GitHubの例¶

GitHubは、リッチだがレート制限のあるREST APIを提供するクラウドベースのソフトウェアソースコードリポジトリです。GitHub REST APIドキュメント。（このリンクをクリックする前にGitHubにログインしてください。）

レート制限¶

• GitHub APIレート制限リリファレンス： https://developer.github.com/v3/rate_limit/（このリンクをクリックする前にGitHubにログインしてください。）

• GitHubでは、1時間あたり5000件のリクエストが許可されており、具体的な制限はサービスごとに異なります。

• レート制限は、認証されていないユーザーと認証されたユーザーで異なります。

ページ付け¶

• GitHubは、RESTデータセットのRFC 5899ページ付けをサポートしています。

• ページ分割されたREST応答の場合、ユーザーはAPI呼び出しごとに1ページのデータ(/search APIの場合は30エントリ)を受け取ります。

• ユーザーは、「ペール_ページ」APIパラメーターを使用して、ページあたりの結果数を最大100までオーバーライドできます。

• ページごとの結果カウントをMaximum（最大）許容設定に設定すると、REST API呼び出しの数が減るため、データインポートのスループットが向上します。

設定¶

• ベースURL： https://api.github.comこのリンクをクリックする前にGitHubにログインしてください。

• リソース：

  • Mozilla Repos：「mozilla」の検索に一致するソフトウェアリポジトリのリストを取得します。
    • 注：このクエリーは、呼び出しごとにデフォルトの30レコードを使用する場合、/ サーチAPIに対するユーザーのクォータを使い果たします。
    • 期待される結果数 > 6600
    • Mozillaリポジトリ：/search/repositories？q=mozilla

• Mozillaリポジトリページ33+：結果の33ページから始まる検索セットを実行する例

  • Mozilla Repos Page 33:search/repositories?q=mozilla&page=33

• Square Repos：Square組織に属するリポジトリのリストを取得します。

  • Square Repos：/orgs/square/repos

• 組織：要求あたり100件のレコードを使用して、すべてのGitHubの組織のページ化されたリストを取得します。警告：この場合、200万件以上のエントリをプルするために長時間実行されます。

  • Organizations:/organizations?per_page=100

Jiraの例¶

Jiraは、通常、ソフトウェア開発チームが使用するプロジェクトおよび課題追跡ソフトウェアです。Jira REST APIドキュメント。

レート制限、ページ付け、および設定¶

• レート制限は、サブスクリプションレベルによって異なります。

• Jira REST APIは、データのページごとに最大100件の結果を返すように制限されています。

• JiraはRFC 5899のページ付けをサポートしていません。

• Jira クラウドインスタンスでは、ユーザーがJIRA REST APIトークンを作成する必要がある場合があります。

• トークンを作成します。https://confluence.atlassian.com/cloud/api-tokens-938839638.html

• 認証タイプ：基本認証

• ユーザー名フィールドのユーザー名

• パスワードフィールドのAPIトークン

設定¶

• ベースURL：

• オンプレミス： https://(hostname):(port)/rest/api/

• Jira クラウド： https://(your-domain).atlassian.net/rest/api/

• リソース

• 全プロジェクトリスト：

  • 全プロジェクト：/project

• JQLリソースの例：Jira JQLクエリーを実行して200のTo-Doタスクアイテムを取得します。

  • JQLクエリーは、設定に貼り付ける前にURLエンコードする必要がありました。
  • Connector To Do Tasks：/search?jql=Project%3D_yourProject_%20and%20statusCategory%3D%22To%20Do%22&maxResults=200

• 認証：基本（ユーザー名/パスワード）

JIRAのページ付け¶

JiraはRFC 5899のページ付けをサポートしていません。JIRAのページ付けをサポートするには：

• データのページを指定するデータソースリソースエントリを定義します。

• 「maxResults=100」を使用して、REST呼び出しごとのエントリ数を最大化します。

• 開始点の指定には「startAt=N」を使用します。Nは0から始まります。

• 例：100件の検索結果の4ページ

  • すべての問題 0：/search？jql=&startAt=0&maxResults=100 すべての問題 1：/search？jql=&startAt=100&maxResults=100 すべての問題 2：/search？jql=&startAt=200&maxResults=100 すべての問題 3：/search？jql=&startAt=300&maxResults=100

• Data Prepのワイルドカード機能を使用して、データのすべてのページを選択

• ワイルドカードパターン= "すべての問題*"

  

• JSONをフラット化し、サブタスクを説明するためにいくつかの行を複製するJSON解析の後、557行のデータX 298列を取得しました。

米国国勢調査データの例¶

国勢調査データWebサイトはREST APIではありませんが、REST APIコネクターを使用してHTTP経由でデータを取得できます。

• ベースURL： https://www2.census.gov/

• American Community Survey 2002のリソース例

ACS_2002_Midwest:/acs2002/2007_prod_release1/BaseTablesSubjectTables/Region/MidwestRegionBaseTables02000US2.csv

ACS_2002_US_OH_Franklin:/acs2002/2007_prod_release1/BaseTablesSubjectTables/States/Ohio/StateCounty/FranklinCountyOhio/BaseTables05000US39049.csv

ACS_2002_Base_California:/acs2002/2007_prod_release1/BaseTablesSubjectTables/States/California/CaliforniaBaseTables04000US06.csv

• 認証：なし

• 「ACS 2002 Base」データのすべてのページを選択するには、Data Prepのワイルドカード機能を使用します。 ワイルドカードパターン：

• 「ACS2002ベースA *」：アラバマ、アラスカ、アーカンソー、アリゾナのファイルを1つのデータセットとしてインポートします。

• 「ACS2002ベース*」：一致するすべての「ACS2002ベース」ファイルを1つのデータセットとしてインポートします。