[ベータ版]{class="badge informative"}
Flow Service APIを使用してSAP Commerceのソース接続とデータフローを作成する
NOTE
SAP Commerce ソースはベータ版です。 ベータ版のソースの使用について詳しくは、 ソースの概要を参照してください。
次のチュートリアルでは、Flow Service APIを使用してSAP サブスクリプション請求の連絡先と顧客データをAdobe Experience Platformに取り込むためのSAP Commerce ソース接続とデータフローを作成する手順について説明します。
はじめに
このガイドは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。
- ソース : Experience Platformを使用すると、様々なソースからデータを取り込むことができますが、Experience Platform サービスを使用して着信データを構造化、ラベル付け、強化することができます。
- サンドボックス : Experience Platformは、1つのExperience Platform インスタンスを個別のバーチャル環境に分割して、デジタルエクスペリエンスアプリケーションの開発と進化に役立つバーチャルサンドボックスを提供します。
次の節では、Flow Service APIを使用してSAP Commerceに正常に接続するために知っておく必要がある追加情報を示します。
必要な資格情報の収集
SAP CommerceをExperience Platformに接続するには、次の接続プロパティの値を指定する必要があります。
資格情報
説明
clientIdサービス キーからの
clientIdの値。clientSecretサービス キーからの
clientSecretの値。tokenEndpointサービス キーの
urlの値は、https://subscriptionbilling.authentication.eu10.hana.ondemand.comと似ています。regionデータセンターの場所： この領域は
urlに存在し、eu10またはus10と同様の値を持ちます。 例えば、urlがhttps://subscriptionbilling.authentication.eu10.hana.ondemand.comの場合、eu10が必要です。これらの資格情報について詳しくは、SAP Commerce ドキュメント を参照してください。
Flow Service APIを使用してSAP CommerceをExperience Platformに接続します
次に、SAP Commerce ソースの認証、ソース接続の作成、およびアカウントと連絡先のデータをExperience Platformに取り込むためのデータフローの作成を行うために必要な手順の概要を示します。
ベース接続の作成 base-connection
ベース接続は、ソースの認証情報、接続の現在の状態、一意のベース接続IDなど、ソースとExperience Platform間の情報を保持します。 ベース接続 ID により、ソース内からファイルを参照および移動し、データタイプやフォーマットに関する情報を含む、取り込みたい特定の項目を識別することができます。
ベース接続IDを作成するには、SAP Commerce認証情報をリクエスト本文の一部として提供しながら、/connections エンドポイントにPOST リクエストを行います。
API 形式
POST /connections
リクエスト
次のリクエストは、SAP Commerce のベース接続を作成します。
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": "SAP Commerce base connection",
"description": "Authenticated base connection for SAP Commerce",
"connectionSpec": {
"id": "d8ee38de-7ae9-4058-9610-c79ce75f8e92",
"version": "1.0"
},
"auth": {
"specName": "OAuth2 Client Credential",
"params": {
"region": "{REGION}",
"clientId": "{CLIENT_ID}",
"clientSecret": "{CLIENT_SECRET}"
"tokenEndpoint": "{TOKEN_ENDPOINT}"
}
}
}'
プロパティ
説明
nameベース接続の名前。 ベース接続の情報を検索する際に使用できるので、ベース接続の名前はわかりやすいものにしてください。
descriptionベース接続に関する詳細情報を提供するために含めることができるオプション値。
connectionSpec.idソースの接続仕様 ID。 この ID は、ソースが登録および承認された後に、Flow Service API から取得することができます。
auth.specNameExperience Platformに対するソースの認証に使用する認証タイプ。
auth.params.regionデータセンターの場所： この領域は
urlに存在し、eu10またはus10と同様の値を持ちます。 例えば、urlがhttps://subscriptionbilling.authentication.eu10.hana.ondemand.comの場合、eu10が必要です。auth.params.clientIdサービス キーからの
clientIdの値。auth.params.clientSecretサービス キーからの
clientSecretの値。auth.params.tokenEndpointサービス キーの
urlの値は、https://subscriptionbilling.authentication.eu10.hana.ondemand.comと似ています。応答
リクエストが成功した場合は、一意の接続識別子（id）を含む、新しく作成されたベース接続が返されます。 この ID は、次の手順でソースのファイル構造と内容を調べるために必要です。
{
"id": "5f6d6022-3f64-400c-ba01-d4010de2d8ff",
"etag": "\"f8018de1-0000-0200-0000-6482d7210000\""
}
ソースを参照 explore
ベース接続IDを取得したら、ベース接続IDをクエリパラメーターとして提供しながら、/connections エンドポイントに対してGET リクエストを実行して、ソースデータのコンテンツと構造を調査できるようになりました。
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でエンコードする必要があります。
SAP Commerceは複数のAPIをサポートしています。 使用しているオブジェクトタイプに応じて、次のいずれかを渡します。
customerscontacts
SAP Commerce ソースは複数のAPIをサポートしています。 送信するリクエストを活用しているオブジェクトタイプに応じて、次の手順を実行します。
NOTE
レスポンスレコードの中には、より良いプレゼンテーションを可能にするために切り捨てられたものもあります。
お客様
| accordion | ||
|---|---|---|
| リクエスト | ||
|
SAP Commerce Customers APIの場合、
|
| accordion | ||
|---|---|---|
| 応答 | ||
|
応答が成功すると、次のようなJSON構造が返されます。
|
連絡先
| accordion | ||
|---|---|---|
| リクエスト | ||
|
SAP Commerce件の連絡先APIの場合、
|
| accordion | ||
|---|---|---|
| 応答 | ||
|
応答が成功すると、次のようなJSON構造が返されます。
|
ソース接続の作成 source-connection
ソース接続を作成するには、Flow Service APIの/sourceConnections エンドポイントに対してPOST リクエストを行います。 ソース接続は、接続 ID、ソースデータファイルへのパス、接続仕様 ID から構成されます。
API 形式
POST /sourceConnections
使用しているオブジェクトタイプに応じて、以下のタブから選択します。
お客様
| accordion | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| リクエスト | ||||||||||||||||||||
|
次のリクエストは、SAP Commerce人の顧客データのソース接続を作成します。
|
| accordion | ||
|---|---|---|
| 応答 | ||
|
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（
|
連絡先
| accordion | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| リクエスト | ||||||||||||||||||||
|
次のリクエストは、SAP Commerce件の連絡先データのソース接続を作成します。
|
| accordion | ||
|---|---|---|
| 応答 | ||
|
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（
|
ターゲット 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
リクエスト
次のリクエストは、SAP Commerce のターゲット接続を作成します。
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": "SAP Commerce Target Connection Generic Rest",
"description": "SAP Commerce Target Connection Generic Rest",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/325fd5394ba421246b05c0a3c2cd5efeec2131058a63d473",
"version": "1.2"
}
},
"params": {
"dataSetId": "645923cd7aeeea1c06c5e92e"
}
}'
プロパティ
説明
nameターゲット接続の名前。 ターゲット接続の情報を検索に使用できるように、ターゲット接続はわかりやすい名前にしてください。
descriptionターゲット接続に関する詳細を提供するために含めることができるオプションの値です。
connectionSpec.idデータレイクに対応する接続仕様ID。 この修正済み ID は
6b137bf6-d2a0-48c8-914b-d50f4942eb85 です。data.format取り込む SAP Commerce データの形式。
params.dataSetId前の手順で取得したターゲットデータセット ID。
応答
リクエストが成功した場合は、新しいターゲット接続の一意の ID（id）が返されます。 この ID は、後の手順で必要になります。
{
"id": "5b72a4b6-2fb8-4ca7-8ad8-4114a3063c5c",
"etag": "\"db00c6dc-0000-0200-0000-6482d8280000\""
}
マッピングの作成 mapping
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。 これは、リクエストペイロード内で定義されたデータマッピングを使用して、Data Prep APIに対してPOST リクエストを実行することで実現します。
API 形式
POST /conversion/mappingSets
お客様
| accordion | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| リクエスト | ||||||||||||||
|
次のリクエストは、SAP Commerceの顧客API データのマッピングを作成します
|
| accordion | ||
|---|---|---|
| 応答 | ||
|
リクエストが成功した場合は、一意の ID（
|
連絡先
| accordion | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| リクエスト | ||||||||||||||
|
次のリクエストは、SAP Commerce連絡先API データのマッピングを作成します
|
| accordion | ||
|---|---|---|
| 応答 | ||
|
リクエストが成功した場合は、一意の ID（
|
フローの作成 flow
SAP CommerceからExperience Platformにデータを取り込む最後の手順は、データフローを作成することです。 現時点で、次の必要な値の準備ができています。
データフローは、ソースからデータをスケジュールおよび収集する役割を果たします。 ペイロードに前述の値を提供しながら POST リクエストを実行することで、データフローを作成することができます。
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": "SAP Commerce Connector Description Flow Generic Rest",
"description": "SAP Commerce Connector Description Flow Generic Rest",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"2ef2e831-f4f1-4363-a0f7-08b4ea347164"
],
"targetConnectionIds": [
"5b72a4b6-2fb8-4ca7-8ad8-4114a3063c5c"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "ddf0592bcc9d4ac391803f15f2429f87",
"mappingVersion": "0"
}
}
],
"scheduleParams": {
"startTime": "1625040887",
"frequency": "once",
}
}'
プロパティ
説明
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データフローがデータを収集する頻度。
scheduleParams.intervalインターバルは 2 つの連続したフロー実行の間隔を指定します。 インターバルの値はゼロ以外の整数にしてください。
応答
正常な応答は、新しく作成したデータフローの 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