Fxiaokeデータソースの設定
Fxiaokeデータソースは、オフライン同期でCRMオブジェクトのデータを読み取り、プラットフォームのプリセットデータウェアハウスに書き込むために使用します。このドキュメントでは、Fxiaoke側でのアプリの権限付与、データソースの設定、同期プランの作成、タスクフローへのマウントについて説明します。
使用制限と事前準備
設定を始める前に、以下の制限と前提条件を確認してください:
- Fxiaokeはデータの読み取り元としてのみ使用でき、データの流向としては使用できません。また、Fxiaokeへの書き戻しも行いません。
- アプリ管理権限を持つ企業管理者が自社開発アプリを作成・管理し、CRM管理者がアクセスに使用する従業員のオブジェクト、フィールド、レコードの権限を設定する必要があります。
- アクセス用のIDとして、有効で長期的に管理できる従業員アカウントを用意し、アカウントの責任者と権限管理者を明確にしてください。
- 同期するオブジェクト、フィールド、レコードの範囲を確認し、プラットフォームの実行環境から企業が利用するクラウドのFxiaokeオープンプラットフォームにアクセスできることを確認してください。
| 環境の構成方法 | 適用シナリオ | 設定要件 |
|---|---|---|
| 環境を区別しない | 開発環境と本番環境で接続設定を共用 | アプリの認証情報とEmployee IDを1組用意し、アクセス権限が要件を満たすことを確認 |
| 独立環境構成 | 開発環境と本番環境の接続設定を個別に管理 | 使用可能な認証情報とEmployee IDをそれぞれ用意し、両環境のオブジェクトとフィールドの権限を確認して、個別に接続性テストを実施 |
Fxiaokeでのアプリの権限付与
企業の自社開発アプリの作成と有効化
- 企業管理者のアカウントでFxiaokeのWeb版にログインし、管理画面を開きます。
- アプリ一覧 を開き、企業の自社開発アプリを新規作成 を選択して、アプリ名や説明などを入力し、保存します。
- アプリの設定ページを開き、開発者モードを有効にして、画面の指示に従い、ログイン認可を開始するページのドメインとIP許可リストを設定します。
- 現在の企業でアプリが有効になっていることを確認し、App ID、App Secret、Permanent Code(永続認可コード) を取得します。
IP許可リストには、プラットフォームのデプロイ・保守担当者から提供された、実際にAPIリクエストを送信するサーバーの外向きパブリックIP を登録してください。出口が複数ある場合は、すべて登録します。ブラウザーを使用しているPCのIPを、サーバーの外向きIPとして渡さないでください。
具体的な操作画面と設定方法は、Fxiaoke公式のクイックスタートを参照してください。
アプリのクエリ権限と従業員のデータ権限の付与
自社開発アプリの CRM APIクエリ権限設定 を開き、読み取るオブジェクトの範囲に応じて、以下のクエリ権限を付与します。
| 権限の用途 | APIパス |
|---|---|
| オブジェクト一覧の取得 | /cgi/crm/v2/object/list |
| オブジェクトの詳細とフィールド情報の取得 | /cgi/crm/v2/object/describe |
| プリセットオブジェクトのデータの取得 | /cgi/crm/v2/data/query |
| カスタムオブジェクトのデータの取得 | /cgi/crm/custom/v2/data/query |
アプリのAPI権限と従業員のデータ権限は、個別に設定する必要があります。CRM管理者は、アクセスに使用する従業員について、以下も確認してください:
| 権限の階層 | 確認内容 |
|---|---|
| オブジェクト権限 | 同期する業務オブジェクトを表示できること |
| フィールド権限 | 同期するフィールドを読み取れること |
| レコードの範囲 | 該当する部署、担当者、共有範囲のデータなど、業務で必要な範囲のレコードを表示できること |
たとえば、ある部署の顧客レコードを読み取る場合、従業員のデータアクセス範囲にその部署が含まれる必要があります。自分のレコードしか表示できない従業員について、その部署の全レコードへの権限を取得済みとして検証を完了しないでください。詳細は公式のデータ権限の説明を参照してください。
Employee IDの取得と権限付与結果の確認
管理者に対象従業員の openUserId を確認してもらい、データソースの Employee ID として使用します。公式の部署内メンバーの基本情報の取得など、管理者向けの手順で対象者を確認し、返された openUserId を記録してください。携帯電話番号、ログインアカウント、社員番号、企業IDは入力しないでください。
管理者に、企業が利用するクラウドに対応したAPIドメインを確認してもらってください。デフォルト値は open.fxiaoke.com です。他のクラウドのドメインは、公式の企業が利用するクラウドのドメインの説明を参照し、現在のプラットフォームがその設定を受け付けることも確認してください。公式のクラウドドメイン一覧にあるすべてのドメインが、現在のプラットフォームでサポートされているとは限りません。
権限付与が完了したら、APIドメイン、App ID、App Secret、Permanent Code、Employee ID、許可したデータ範囲、登録した外向きIP、保守責任者をプラットフォームの設定担当者に引き渡します。App SecretとPermanent Codeは、企業が承認した安全な経路で引き渡し、通常のドキュメント、ログ、チケットに記載しないでください。
同じアプリ、同じEmployee ID、実際のサーバーのネットワーク出口 を使用して、認証情報、API、オブジェクト、フィールド、レコードの範囲を確認してください。アプリが有効になっていることやアクセストークンを取得できることだけでは、従業員に必要なすべてのデータ権限が付与されたことにはなりません。
Fxiaokeデータソースの作成
- データ開発プラットフォーム > 連携 > データソース に移動し、+ データソース をクリックします。
- Fxiaoke を選択し、次のステップ をクリックして、データソース名と備考を入力します。
- 環境を区別しない または 独立環境構成 を選択します。独立環境構成では、開発環境と本番環境の設定をそれぞれ完了する必要があります。
- API Domain、App ID、App Secret、Permanent Code、Employee IDを入力します。
- 接続性テスト で テスト をクリックします。接続可能 と表示されたら、完了 をクリックします。
接続パラメーターを入力し、環境の構成方法を確認します。
| 構成項目 | 説明 |
|---|---|
| データソース名 | 現在のスペース内のデータソース名。画面の名前および一意性の検証に合格する必要があります |
| 備考 | 任意。用途や保守に関する情報を記載します |
| API Domain | FxiaokeオープンプラットフォームのAPIドメイン。デフォルトは open.fxiaoke.com。企業が利用するクラウドとプラットフォームのサポート状況に応じて設定します |
| App ID | 企業の自社開発アプリのアプリID。必須 |
| App Secret | 上記アプリのアプリシークレット。必須 |
| Permanent Code | 上記アプリの永続認可コード。必須 |
| Employee ID | データの読み取りに使用する従業員の openUserId。必須。その従業員に必要なデータ権限が付与されている必要があります |
保存済みのデータソースを編集する場合、App SecretとPermanent Codeはマスクされた値で表示されます。マスクされた値をそのまま残すと、元の認証情報が引き続き使用されます。変更する場合は、新しい値を入力して、再度接続性テストを実施してください。
接続性テストに合格した後も、オフライン同期プランで対象オブジェクト、フィールド、レコードの範囲を確認する必要があります。独立環境構成では、開発環境と本番環境のアクセス権限をそれぞれ確認してください。
オフライン同期プランの作成
- データ開発プラットフォーム > 連携 > オフライン同期 に移動し、+ 統合プラン をクリックします。
- データソース で Fxiaoke と作成済みのデータソースを選択します。
- オブジェクトタイプ として、プリセットオブジェクト または カスタムオブジェクト を選択します。
- ソースオブジェクト でオブジェクト名またはAPI名を検索し、同期するオブジェクトを選択します。
- データプレビュー をクリックし、ソースオブジェクトと読み取り可能なデータの内容が想定どおりであることを確認します。
オブジェクトタイプとソースオブジェクトを選択してから、データをプレビューします。
オブジェクトタイプを切り替えると、それまでに選択したオブジェクトとフィールドマッピングはクリアされます。ソースオブジェクトを選択し直し、フィールドマッピングを再度確認してください。ソースオブジェクトを選択するまで、データプレビューは使用できません。
フィールドマッピングと同期の検証
対応するフィールドタイプ
| フィールド区分 | 対応するFxiaokeのフィールドタイプ |
|---|---|
| テキストと単一値の参照 | text、long_text、html_rich_text、phone_number、email、url、auto_number、select_one、master_detail、object_reference |
| 地域と位置 | country、province、city、district、location |
| 複数値フィールド | select_many、department、department_many、employee、employee_many、object_reference_many、tag、array |
| 数値 | number、currency、percentile |
| ブール値 | true_or_false |
| 日付と時刻 | date、date_time、time |
| 計算結果と参照結果 | count、formula、quote。画像、添付ファイル、署名の結果は含みません |
上記のフィールドを読み取る際は、以下の要件も満たす必要があります。
- テキストと単一値の参照、地域と位置のフィールドは、値が文字列である必要があります。複数値フィールドは文字列配列である必要があり、配列にはNULL値を含めることができます。
- 数値フィールドでは小数点以下の桁数を明示する必要があり、その範囲は0~38です。実際の数値の総精度は38桁以内とし、有効な小数点以下の桁数はフィールドで宣言された範囲内である必要があります。
- ブールフィールドはブール値である必要があります。日付フィールドと日時フィールドには整数のミリ秒タイムスタンプ、時刻フィールドには整数値が必要です。
- 計算フィールドと参照フィールドは既存の結果を読み取ります。結果はテキスト、数値、ブール値、または有効な配列やオブジェクトの内容である必要があります。その他のフィールドタイプは、まずデータプレビューと手動実行で読み取り結果を確認してください。
非対応のフィールドと制限
- 画像(
image)、添付ファイル(file_attachment)、署名(signature)、およびquote(image)など、これらの内容を返す参照結果の読み取りには対応していません。その他のフィールドの結果にも添付ファイルや画像などのメディアが含まれる場合、通常のフィールド内容として同期することはできません。 - タイプの宣言がない場合や、数値フィールドに有効な小数点以下の桁数の宣言がない場合、そのフィールドは使用できません。画面では、読み取りに対応していないソースフィールドはグレー表示されます。表示される理由を確認してください。
- 有効になっていないフィールドは読み取り対象になりません。フィールドグループ(
group)自体は独立したフィールドとして読み取りませんが、その子フィールドは各自のタイプに従って選択できます。
構成と検証
データソースの設定が完了したら、データの流向 でプラットフォームのプリセットデータウェアハウスの目標テーブルを選択または作成し、フィールドマッピングを設定します。
独立環境構成では、手動実行にも本番環境のデータソース設定が使用されます。実行前に、本番環境の認証情報、オブジェクトとフィールドの権限、および目標テーブルが想定どおりであることを確認してください。
- 業務上の必要に応じて、目標テーブルと書き込み方法を設定します。
- フィールドマッピングで、読み取るソースフィールドを目標フィールドにマッピングします。
- グレー表示のフィールドを使用可能なフィールドとして設定しないでください。表示される案内に従って、同期するフィールドを調整してください。
- プラン名、責任者、備考を入力して保存します。
- 手動実行 をクリックし、実行記録でタスクの成功を確認してから、目標テーブルで行数、フィールド、データの内容を確認します。
ソースフィールドの名前は業務上の意味を識別するために、API名は対応するフィールドを区別するために使用します。設定後はマッピングを1つずつ確認し、表示名が似たフィールドを誤って関連付けないようにしてください。
以下はフィールドマッピング画面の例です。実際の業務に合わせてフィールドの対応関係を確認してください。
| 現象 | 確認事項 |
|---|---|
| 接続性テストに失敗する | API Domain、4つの認証情報とその対応関係を確認し、アプリと従業員アカウントが無効化されていないことを確認 |
| IPが許可されていない、またはアクセスが拒否されたと表示される | デプロイ・保守担当者に実際のサーバーの外向きIPを確認してもらい、アプリのIP許可リストに漏れなく登録されていることを確認 |
| オブジェクト一覧が空、または対象オブジェクトが見つからない | オブジェクトタイプが正しいこと、アプリにオブジェクト一覧の取得権限とクエリ権限が付与されていること、アクセスする従業員にそのオブジェクトの権限があることを確認 |
| フィールドが表示されない、または読み取れない | アプリのオブジェクト詳細の取得権限と従業員のフィールド読み取り権限を確認し、オブジェクト構造が変更されていないか確認 |
| プレビューまたは同期のレコード数が想定より少ない | 同じEmployee IDで従業員の部署、担当者、共有範囲を確認し、読み取れるレコードが業務要件を満たすことを確認 |
| ソースフィールドがグレー表示される、または読み取れない | フィールドの案内を確認し、フィールドタイプと実際の内容が対応範囲内にあるか確認してください |
| 開発環境では正常だが、本番タスクが失敗する | 本番環境の認証情報、外向きIP、アプリ権限、従業員のデータ範囲、および選択したオブジェクトとフィールドにアクセスできることを確認 |
タスクフローへのマウント
手動での検証に成功したら、オフライン同期プランをタスクフローにマウントして、スケジュール周期に従って自動実行できます。
- 保存済みのオフライン同期プランを開き、ジョブフローにマウントする をクリックします。
- 対象のタスクフローを選択します。
- ノード名を入力し、実行モードを選択して、必要に応じて責任者と備考を設定します。ノードタイプと統合プランは自動的に入力されます。
- ノードを作成し、マウントします をクリックします。マウントに成功したら、タスクフローに進む をクリックして、ノードの位置と上流・下流の依存関係を確認できます。
- タスクフローを保存してリリースします。本番のスケジュールでは、本番環境のデータソース設定が使用されます。
リリース前に、本番環境のアプリ、Employee ID、外向きIP、およびオブジェクト、フィールド、レコードの権限がすべて準備できていることを確認してください。同期プランやデータソースを変更する場合は、まず既存のタスクフローの依存関係を評価し、変更後に再度検証してください。

