接続の確立
コネクタ内で利用可能なオブジェクトは、"cdata.zuora" モジュールからアクセスできます。モジュールのオブジェクトを直接使用するには：
- モジュールを以下のようにインポートします。
import cdata.zuora as mod
- 接続を確立するには、以下のような適切な接続文字列を使用してコネクタオブジェクトからconnect() メソッドを呼び出します。
mod.connect("InitiateOAuth=GETANDREFRESH;OAuthClientID=MyOAuthClientId;OAuthClientSecret=MyOAuthClientSecret;Tenant=USProduction;ZuoraService=DataQuery;")
Zuora への接続
Zuora への有効な接続を作成するには、テナントプロパティを設定する必要があります。 アカウント構成に適したテナント値を選択します。利用可能なオプション：- USProduction：リクエストはhttps://rest.zuora.com（デフォルト）に送信されます。
- USAPISandbox：リクエストはhttps://rest.apisandbox.zuora.com に送信されます。
- USPerformanceTest：リクエストはhttps://rest.pt1.zuora.com に送信されます。
- EUProduction：リクエストはhttps://rest.eu.zuora.com に送信されます。
- EUSandbox：リクエストはhttps://rest.sandbox.eu.zuora.com に送信されます。
テナントを設定したのち、トークンを生成するためにカスタムOAuth アプリケーションを作成する必要があります。これは一度きりの簡単な操作です。詳しくは、カスタムOAuth アプリケーションの作成 を参照してください。
Zuora への認証
デスクトップアプリケーション
カスタムOAuth アプリケーションの資格情報を使用して認証するには、カスタムアプリケーションを作成してOAuth アクセストークンを取得し、更新する必要があります。 これらを設定すると、接続の準備が整います。次の接続プロパティを設定します。
- OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
- CallbackURL：アプリケーションの登録時に定義されたリダイレクトURI。
ログインして、アプリケーションにアクセス許可を与えます。本製品 はこれでOAuth プロセスを完了します。
- 本製品 はZuora からアクセストークンを取得し、それを使ってデータをリクエストします。
- OAuth 値はOAuthSettingsLocation で指定されたパスに保存されます。これらの値は接続間で永続化されます。
- アクセストークンの期限が切れたときは、本製品 はアクセストークンを自動でリフレッシュします。
Web アプリケーション
カスタムOAuth アプリケーションの資格情報を使用してWeb から認証するには、Zuora でカスタムOAuth アプリケーションを登録する必要があります。 それから本製品 を使用してOAuth トークンの値を取得および管理します。このセクションでは、OAuth アクセストークンの取得方法、ドライバーにOAuth アクセストークンを自動的に更新させる方法、OAuth アクセストークンを手動で更新する方法について説明します。
OAuth アクセストークンの取得：
次の接続プロパティを設定し、OAuthAccessToken を取得します。
- OAuthClientId：アプリケーション設定のクライアントId。
- OAuthClientSecret：アプリケーション設定のクライアントシークレット。
OAuth 交換を完了するには、以下のようにストアドプロシージャを呼び出します。
- ログインしてWeb アプリケーションを認可します。コールバックURL にリダイレクトされます。
- GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、リダイレクトURI のクエリ文字列のcode パラメータに設定します。
アクセストークンとリフレッシュトークンを取得したのち、データに接続してOAuth アクセストークンを自動的にリフレッシュできます。
OAuth アクセストークンの自動リフレッシュ：
本製品 がOAuth アクセストークンを自動でリフレッシュするようにしたい場合、以下の手順に従います。
はじめてデータに接続する前に、次の接続プロパティを設定します。
- InitiateOAuth：REFRESH。
- OAuthClientId：アプリケーション設定のクライアントId。
- OAuthClientSecret：アプリケーション設定のクライアントシークレット。
- OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークン。
- OAuthSettingsLocation：本製品 がOAuth 値を保存する場所のパス。これは接続間で維持されます。
その後のデータ接続では、以下の接続パラメータを設定します。
- InitiateOAuth
- OAuthSettingsLocation
OAuth アクセストークンの手動リフレッシュ：
OAuth アクセストークンを手動でリフレッシュするために必要な唯一の値は、OAuth リフレッシュトークンです。
- ExpiresIn 期間（GetOAuthAccessToken が返す）が経過した後にOAuthAccessToken を手動でリフレッシュするには、RefreshOAuthAccessToken ストアドプロシージャを呼び出します。
- 次の接続プロパティを設定します。
- OAuthClientId：アプリケーション設定のクライアントId。
- OAuthClientSecret：アプリケーション設定のクライアントシークレット。
- RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを設定します。
- 新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定します。これで新規接続が開かれます。
OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。
ヘッドレスマシン
ヘッドレスマシンのユーザーアカウントでOAuth 認証する必要がある場合は、インターネットブラウザに対応した別の端末で認証する必要があります。 以下のいずれかの方法で行います。
- オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
- オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
オプション1またはオプション2を実行後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするようにドライバーを設定します。
オプション1：Verifier code を取得および交換
Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。以下の手順に従います。
- 次のプロパティを設定します。
- InitiateOAuth：OFF。
- OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
- ログインして、本製品 にアクセス許可を与えます。リダイレクトURI にリダイレクトされます。
- リダイレクトURI に付加されるcode パラメータを控えておきます。これは、後ほどOAuthVerifier 接続プロパティを設定する際に使用します。
- OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換するために、OAuth 認証値を指定する次の接続プロパティを設定します。
- InitiateOAuth：REFRESH。
- OAuthVerifier：控えておいたverifier code（リダイレクトURI のcode パラメータの値）。
- OAuthClientId：カスタムOAuth アプリケーション設定のクライアントId。
- OAuthClientSecret：カスタムOAuth アプリケーション設定のクライアントシークレット。
- OAuthSettingsLocation：暗号化されたOAuth 認証値を指定されたファイルに永続化。
- 接続をテストしてOAuth 設定ファイルを生成し、以下のプロパティを再設定して接続します。
- InitiateOAuth：REFRESH。
- OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
- OAuthSettingsLocation：暗号化されたOAuth 認証値を含むファイル。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品 に読み書きのアクセス許可を与えることを確認してください。
オプション2：OAuth 設定を転送
ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続をインストールし、作成する必要があります。 上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。
「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定されたパスに暗号化されて書き込まれます。 デフォルトのファイル名は"OAuthSettings.txt" です。
接続をテストしてOAuth 設定ファイルを生成し、OAuth 設定ファイルをヘッドレスマシンにコピーします。
ヘッドレスマシンでデータに接続するには、次の接続プロパティを設定します。
- InitiateOAuth：REFRESH。
- OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
- OAuthSettingsLocation：ブラウザでマシンからコピーしたOAuth 設定ファイルへのパス。 アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品 に読み書きのアクセス許可を与えることを確認してください。
Zuora サービスの選択
データクエリとAQuA API の2つのZuora サービスを使用します。デフォルトでは、ZuoraService はAQuADataExport に設定されています。DataQuery
データクエリ機能は、非同期の読み取り専用SQL クエリを実行することで、Zuora テナントからのデータのエクスポートを実現します。 このサービスは、素早く軽量なSQL クエリでの使用を推奨します。制限
- フィルタ適用後の、テーブルごとの入力レコードの最大数： 1,000,000
- 出力レコードの最大数： 100.000
- テナントごとの、実行用に送信される同時クエリの最大数： 5
- テナントごとの、同時クエリの制限に達した後に実行用に送信され、キューに追加されるクエリの最大数： 10
- 1時間単位での、各クエリの最大処理時間： 1
- GB 単位での、各クエリに割り当てられるメモリの最大サイズ： 2
- Index Join を使用する際のインデックスの最大値。言い換えれば、Index Join を使用する際にWHERE 句で使われる一意の値に基づいた、左のテーブルから返されるレコードの最大数： 20.000
Zuora サービスの選択
データクエリとAQuA API の2つのZuora サービスを使用します。デフォルトでは、ZuoraService はAQuADataExport に設定されています。DataQuery
データクエリ機能は、非同期の読み取り専用SQL クエリを実行することで、Zuora テナントからのデータのエクスポートを実現します。 このサービスは、素早く軽量なSQL クエリでの使用を推奨します。制限
- フィルタ適用後の、テーブルごとの入力レコードの最大数： 1,000,000
- 出力レコードの最大数： 100.000
- テナントごとの、実行用に送信される同時クエリの最大数： 5
- テナントごとの、同時クエリの制限に達した後に実行用に送信され、キューに追加されるクエリの最大数： 10
- 1時間単位での、各クエリの最大処理時間： 1
- GB 単位での、各クエリに割り当てられるメモリの最大サイズ： 2
- Index Join を使用する際のインデックスの最大値。言い換えれば、Index Join を使用する際にWHERE 句で使われる一意の値に基づいた、左のテーブルから返されるレコードの最大数： 20.000
AQuADataExport
AQuA API のエクスポートは、すべてのオブジェクト（テーブル）のすべてのレコードをエクスポートするように設計されています。AQuA のクエリジョブには以下の制限があります。制限
- AQuA のジョブ内のクエリが8時間以上実行されている場合、ジョブは自動的に停止されます。
- 停止されたAQuA のジョブは3回再試行可能で、その後失敗として返されます。