Flow Service APIを使用してSugarCRM Accounts & Contactsのソース接続とデータフローを作成する
次のチュートリアルでは、SugarCRM Accounts & Contacts ソース接続を作成し、SugarCRMのアカウントと連絡先データをFlow Service APIを使用してAdobe Experience Platformに取り込むためのデータフローを作成する手順について説明します。
はじめに
このガイドは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。
- ソース : Experience Platformを使用すると、様々なソースからデータを取り込むことができますが、Experience Platform サービスを使用して着信データを構造化、ラベル付け、強化することができます。
- サンドボックス : Experience Platformは、1つのExperience Platform インスタンスを個別のバーチャル環境に分割して、デジタルエクスペリエンスアプリケーションの開発と進化に役立つバーチャルサンドボックスを提供します。
次の節では、Flow Service APIを使用してSugarCRMに正常に接続するために知っておく必要がある追加情報を示します。
必要な資格情報の収集
SugarCRM Accounts & ContactsをExperience Platformに接続するには、次の接続プロパティの値を指定する必要があります。
資格情報
説明
例
hostソースが接続するSugarCRM API エンドポイント。
developer.salesfusion.comusernameSugarCRM開発者アカウントのユーザー名。
abc.def@example.com@sugarmarketdemo000.compasswordSugarCRM開発者アカウントのパスワード。
123456789Flow Service APIを使用してSugarCRM Accounts & ContactsをExperience Platformに接続します
次に、SugarCRM ソースの認証、ソース接続の作成、およびアカウントと連絡先のデータをExperience Platformに取り込むためのデータフローの作成を行うために必要な手順の概要を示します。
ベース接続の作成 base-connection
ベース接続は、ソースの認証情報、接続の現在の状態、一意のベース接続IDなど、ソースとExperience Platform間の情報を保持します。 ベース接続 ID により、ソース内からファイルを参照および移動し、データタイプやフォーマットに関する情報を含む、取り込みたい特定の項目を識別することができます。
ベース接続IDを作成するには、SugarCRM Accounts & Contacts認証情報をリクエスト本文の一部として提供しながら、/connections エンドポイントにPOST リクエストを行います。
API 形式
POST /connections
リクエスト
次のリクエストは、SugarCRM Accounts & Contacts のベース接続を作成します。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "SugarCRM Accounts & Contacts base connection",
"description": "Create a live inbound connection to your SugarCRM Accounts & Contacts instance, to ingest both historic and scheduled data into Experience Platform",
"connectionSpec": {
"id": "59a4b493-a615-40f9-bd38-f823d0909a2b",
"version": "1.0"
},
"auth": {
"specName": "OAuth2 Refresh Code",
"params": {
"host": "developer.salesfusion.com",
"username": "{SUGARCRM_DEVELOPER_ACCOUNT_USERNAME}",
"password": "{SUGARCRM_DEVELOPER_ACCOUNT_PASSWORD}"
}
}
}'
プロパティ
説明
nameベース接続の名前。 ベース接続の情報を検索する際に使用できるので、ベース接続の名前はわかりやすいものにしてください。
descriptionベース接続に関する詳細情報を提供するために含めることができるオプション値。
connectionSpec.idソースの接続仕様 ID。 この ID は、ソースが登録および承認された後に、Flow Service API から取得することができます。
auth.specNameExperience Platformに対するソースの認証に使用する認証タイプ。
auth.params.hostSugarCRM API ホスト：developer.salesfusion.com
auth.params.usernameSugarCRM開発者アカウントのユーザー名。
auth.params.passwordSugarCRM開発者アカウントのパスワード。
応答
リクエストが成功した場合は、一意の接続識別子（id）を含む、新しく作成されたベース接続が返されます。 この ID は、次の手順でソースのファイル構造と内容を調べるために必要です。
{
"id": "f5421911-6f6c-41c7-aafa-5d9d2ce51535",
"etag": "\"4d08164f-0000-0200-0000-6368b7bf0000\""
}
ソースを参照 explore
前の手順で生成したベース接続IDを使用して、GET リクエストを実行してファイルとディレクトリを探索できます。
次の呼び出しを使用して、Experience Platformに取り込むファイルのパスを検索します。
API 形式
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
ソースのファイル構造とコンテンツを調べるために GET リクエストを実行する場合、次の表に示すクエリのパラメーターを含める必要があります。
パラメーター
説明
{BASE_CONNECTION_ID}前の手順で生成したベース接続 ID。
objectType=rest探索するオブジェクトのタイプ。 現在、この値は常に
restに設定されています。{OBJECT}このパラメーターは、特定のディレクトリを表示する場合にのみ必要です。 値は、参照するディレクトリのパスを表します。 このソースの場合、値は
jsonになります。fileType=jsonExperience Platformに取り込むファイルの種類。 現在、
jsonはサポートされている唯一のファイル形式です。{PREVIEW}接続のコンテンツがプレビューをサポートするかどうかを定義するブール値です。
{SOURCE_PARAMS}Experience Platformに取り込むソースファイルのパラメーターを定義します。 {SOURCE_PARAMS}に対して許可された書式型を取得するには、文字列全体をbase64でエンコードする必要があります。
SugarCRM Accounts & Contactsは複数のAPIをサポートしています。 使用しているオブジェクトタイプに応じて、次のいずれかを渡します。
accounts：組織が関係を持つ会社。contacts：組織が確立された関係を持つ個人。
SugarCRM Accounts & Contactsは複数のAPIをサポートしています。 送信するリクエストを活用しているオブジェクトタイプに応じて、次の手順を実行します。
リクエスト
アカウント
SugarCRM アカウント APIの場合、{SOURCE_PARAMS}の値は{"object_type":"accounts"}として渡されます。 base64でエンコードした場合、次に示すようにeyJvYmplY3RfdHlwZSI6ImFjY291bnRzIn0=と等しくなります。
| code language-shell |
|---|
|
連絡先
SugarCRM件の連絡先APIの場合、{SOURCE_PARAMS}の値は{"object_type":"contacts"}として渡されます。 base64でエンコードされた場合、次に示すようにeyJvYmplY3RfdHlwZSI6ImNvbnRhY3RzIn0=と等しくなります。
| code language-shell |
|---|
|
応答
同様に、受信した応答を活用しているオブジェクトタイプに応じて、次のようになります。
NOTE
より良いプレゼンテーションを得るために、一部のレコードが切り捨てられています。
アカウント
応答が成功すると、次のような構造が返されます。
| code language-json |
|---|
|
連絡先
応答が成功すると、次のような構造が返されます。
| code language-json |
|---|
|
ソース接続の作成 source-connection
Flow Service API に対して POST リクエストを実行することで、ソース接続を作成することができます。 ソース接続は、接続 ID、ソースデータファイルへのパス、接続仕様 ID から構成されます。
API 形式
POST /sourceConnections
リクエスト
次のリクエストは、SugarCRM Accounts & Contacts のソース接続を作成します。
使用しているオブジェクトタイプに応じて、以下のタブから選択します。
アカウント
SugarCRM アカウント APIの場合、object_type プロパティ値はaccountsである必要があります。
| code language-shell |
|---|
|
連絡先
SugarCRM連絡先APIの場合、object_type プロパティ値はcontactsである必要があります。
| code language-shell |
|---|
|
プロパティ
説明
nameソース接続の名前。 ソース接続の情報を検索する際に使用できるので、ソース接続の名前はわかりやすいものにしてください。
description含めることでソース接続に関する詳細情報を提供できるオプションの値です。
baseConnectionIdSugarCRM Accounts & Contacts のベース接続 ID。 この ID は、前の手順で生成されました。
connectionSpec.idソースに対応する接続仕様の ID。
data.format取り込む SugarCRM Accounts & Contacts データの形式。 現在、サポートされているデータ形式は
json のみです。object_typeSugarCRM Accounts & Contactsは複数のAPIをサポートしています。 使用しているオブジェクトタイプに応じて、次のいずれかを渡します。
accounts：組織が関係を持つ会社。contacts：組織が確立された関係を持つ個人。
pathこれは、
object_typeに対して選択した値と同じです。応答
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（id）が返されます。 この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "8f1fc72a-f562-4a1d-8597-85b5ca1b1cd3",
"etag": "\"ed05f1e1-0000-0200-0000-6368b8710000\""
}
ターゲット XDM スキーマの作成 target-schema
ソースデータをExperience Platformで使用するには、必要に応じてソースデータを構造化するターゲットスキーマを作成する必要があります。 その後、ターゲットスキーマを使用して、ソースデータが含まれるExperience Platform データセットを作成します。
Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。
ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。
ターゲットデータセットの作成 target-dataset
Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。
ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。
ターゲット接続の作成 target-connection
ターゲット接続は、取り込んだデータを格納する宛先への接続を表します。 ターゲット接続を作成するには、データレイクに対応する固定接続仕様IDを指定する必要があります。 この ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。
ターゲットスキーマ、ターゲットデータセット、データレイクへの接続仕様IDなどの一意の識別子が作成されました。 これらの識別子を使用すると、受信ソースデータを格納するデータセットを指定する Flow Service API を使用して、ターゲット接続を作成することができます。
API 形式
POST /targetConnections
リクエスト
次のリクエストは、SugarCRM Accounts & Contacts のターゲット接続を作成します。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "SugarCRM Target Connection Generic Rest",
"description": "SugarCRM Target Connection Generic Rest",
"connectionSpec": {
"id": "63d2b27b-69a5-45c9-a7fe-78148a25de3c",
"version": "1.0"
},
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/b156e6f818f923e048199173c45e55e20fd2487f5eb03d22",
"version": "1.22"
}
},
"params": {
"dataSetId": "6365389d1d37d01c077a81da"
}
}'
プロパティ
説明
nameターゲット接続の名前。 ターゲット接続の情報を検索に使用できるように、ターゲット接続はわかりやすい名前にしてください。
descriptionターゲット接続に関する詳細を提供するために含めることができるオプションの値です。
connectionSpec.idデータレイクに対応する接続仕様ID。 この修正済み ID は
6b137bf6-d2a0-48c8-914b-d50f4942eb85 です。data.format取り込む SugarCRM Accounts & Contacts データの形式。
params.dataSetId前の手順で取得したターゲットデータセット ID。
応答
リクエストが成功した場合は、新しいターゲット接続の一意の ID（id）が返されます。 この ID は、後の手順で必要になります。
{
"id": "6b137bf6-d2a0-48c8-914b-d50f4942eb85",
"etag": "\"8405a268-0000-0200-0000-6368b8c30000\""
}
マッピングの作成 mapping
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。 これは、リクエストペイロード内で定義されたデータマッピングを使用して、Data Prep APIに対してPOST リクエストを実行することで実現します。
API 形式
POST /conversion/mappingSets
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"outputSchema": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/b156e6f818f923e048199173c45e55e20fd2487f5eb03d22",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"sourceType": "ATTRIBUTE",
"source": "results.account",
"destination": "_extconndev.account"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.account_id",
"destination": "_extconndev.account_id"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.acount_name",
"destination": "_extconndev.account_name"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.account_score",
"destination": "_extconndev.account_score"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.billing_city",
"destination": "_extconndev.billing_city"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.contacts",
"destination": "_extconndev.contacts"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.created_by",
"destination": "_extconndev.created_by"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.created_by_id",
"destination": "_extconndev.created_by_id"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.created_date",
"destination": "_extconndev.created_date"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.custom_score_field",
"destination": "_extconndev.custom_score_field"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.key_account",
"destination": "_extconndev.key_account"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.owner",
"destination": "_extconndev.owner"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.owner_id",
"destination": "_extconndev.owner_id"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.phone",
"destination": "_extconndev.phone_no"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.updated_by",
"destination": "_extconndev.updated_by"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.updated_by_id",
"destination": "_extconndev.updated_by_id"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.updated_date",
"destination": "_extconndev.updated_date"
}
]
}'
プロパティ
説明
outputSchema.schemaRef.id以前の手順で生成されたターゲット XDM スキーマの ID。
mappings.sourceTypeマッピングするソース属性タイプ。
mappings.source宛先 XDM パスにマッピングする必要があるソース属性。
mappings.destinationソース属性がマッピングされている宛先 XDM パス。
応答
リクエストが成功した場合は、一意の ID（id）を含む、新しく作成されたマッピングの詳細が返されます。 この値は、後の手順でデータフローを作成する際に必要になります。
{
"id": "059c69f7207b4d7e9b48c47e2fd966a6",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
フローの作成 flow
SugarCRM Accounts & ContactsからExperience Platformにデータを取り込む最後の手順は、データフローを作成することです。 現時点で、次の必要な値の準備ができています。
データフローは、ソースからデータをスケジュールおよび収集する役割を果たします。 ペイロードに前述の値を提供しながら POST リクエストを実行することで、データフローを作成することができます。
取り込みをスケジュールするには、まず開始時刻の値をエポック時間（秒）に設定する必要があります。 次に、頻度の値をhourまたはdayのいずれかに設定する必要があります。 インターバル値は、連続する2つの取り込みの間の期間を指定します。 hourまたはdayのscheduleParams.frequencyの選択に応じて、間隔の値を1または24に設定する必要があります。
API 形式
POST /flows
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "SugarCRM Connector Description Flow Generic Rest",
"description": "SugarCRM Connector Description Flow Generic Rest",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"8f1fc72a-f562-4a1d-8597-85b5ca1b1cd3"
],
"targetConnectionIds": [
"6b137bf6-d2a0-48c8-914b-d50f4942eb85"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "059c69f7207b4d7e9b48c47e2fd966a6",
"mappingVersion": "0"
}
}
],
"scheduleParams": {
"startTime": "1625040887",
"frequency": "hour",
"interval": 1
}
}'
プロパティ
説明
nameデータフローの名前。 データフローの情報を検索する際に使用できるので、データフローはわかりやすい名前にしてください。
descriptionデータフローに関する詳細情報を提供するために含めることができるオプション値。
flowSpec.idデータフローの作成に必要なフロー仕様 ID。 この修正済み ID は
6499120c-0b15-42dc-936e-847ea3c24d72 です。flowSpec.versionフロー仕様 ID の対応するバージョン。 この値のデフォルトは
1.0 です。sourceConnectionIds以前の手順で生成されたソース接続 ID。
targetConnectionIds以前の手順で生成されたターゲット接続 ID。
transformationsこのプロパティには、データに適用する必要がある様々な変換が含まれています。 このプロパティは、XDMに準拠していないデータをExperience Platformに取り込む場合に必要です。
transformations.name変換に割り当てられた名前。
transformations.params.mappingId以前の手順で生成されたマッピング ID。
transformations.params.mappingVersionマッピング ID の対応するバージョン。 この値のデフォルトは
0 です。scheduleParams.startTimeこのプロパティには、データフローの取り込みスケジュールに関する情報が含まれます。
scheduleParams.frequencyデータフローがデータを収集する頻度。 指定できる値は
hourまたはdayです。scheduleParams.intervalインターバルは 2 つの連続したフロー実行の間隔を指定します。 インターバルの値はゼロ以外の整数にしてください。
hourまたはdayのscheduleParams.frequencyの選択に応じて、間隔の値を1または24に設定する必要があります。応答
正常な応答は、新しく作成したデータフローの ID（id）を返します。 この ID を使用して、データフローを監視、更新または削除できます。
{
"id": "fcd16140-81b4-422a-8f9a-eaa92796c4f4",
"etag": "\"9200a171-0000-0200-0000-6368c1da0000\""
}
付録
次の節では、データフローを監視、更新、削除する手順について説明します。
データフローの監視
データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。 完全なAPIの例については、APIを使用したソースデータフローの監視に関するガイドを参照してください。
データフローの更新
データフローのIDを指定しながら、Flow Service APIの/flows エンドポイントに対してPATCH リクエストを行うことで、データフローの名前や説明、実行スケジュールおよび関連するマッピングセットなどの詳細を更新します。 PATCH リクエストを行う場合は、If-Match ヘッダーにデータフローの一意のetagを指定する必要があります。 完全なAPI例については、APIを使用したソースデータフローの更新に関するガイドを参照してください
アカウントを更新
ベース接続IDをクエリパラメーターとして指定しながら、Flow Service APIに対してPATCH リクエストを実行して、ソースアカウントの名前、説明、資格情報を更新します。 PATCH リクエストを行う場合、If-Match ヘッダーにソースアカウントの一意のetagを指定する必要があります。 完全なAPIの例については、APIを使用したソースアカウントの更新に関するガイドを参照してください。
データフローの削除
クエリパラメーターの一部として削除するデータフローのIDを指定しながら、Flow Service APIに対してDELETE リクエストを実行して、データフローを削除します。 完全なAPIの例については、APIを使用したデータフローの削除に関するガイドを参照してください。
アカウントを削除
削除するアカウントのベース接続IDを指定しながら、Flow Service APIに対してDELETE リクエストを実行して、アカウントを削除します。 完全なAPIの例については、APIを使用したソースアカウントの削除に関するガイドを参照してください。
recommendation-more-help
experience-platform-help-sources