Flow Service API の mode=draft
クエリパラメーターを使用して、ベース接続、ソース接続、ターゲット接続、データフローなどの Flow Service エンティティをドラフト状態に設定できます。
ドラフトは、後で新しい情報で更新し、準備が整ったら、op=publish
クエリパラメーターを使用して公開できます。
このチュートリアルでは、Flow Service エンティティをドラフト状態に設定し、後で完了するためにワークフローを一時停止して保存できるようにする方法の手順を説明します。
このチュートリアルは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。
Platform API を正常に呼び出す方法について詳しくは、Platform API の概要のガイドを参照してください。
使用しているソースの接続仕様 ID と対応するフロー仕様 ID がドラフトモードで有効になっているかどうかも確認する必要があります。
次のリクエストは、Azure File Storage の接続仕様情報を取得します。
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/be5ec48c-5b78-49d5-b8fa-7c89ec4569b8' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
正常な応答は、ソースの接続仕様情報を返します。ソースでドラフトモードがサポートされているかどうかを確認するには、items[0].attributes.isDraftModeSupported
の値が true
であることを確認します。
{
"items": [
{
"id": "be5ec48c-5b78-49d5-b8fa-7c89ec4569b8",
"name": "azure-file-storage",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"authSpec": [
{
"name": "Basic Authentication",
"type": "basicAuthentication",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines auth params",
"properties": {
"host": {
"type": "string",
"description": "Specifies the Azure File Storage endpoint."
},
"userid": {
"type": "string",
"description": "Specify the user to access the Azure File Storage."
},
"password": {
"type": "string",
"description": "Specify the storage access key",
"format": "password"
}
},
"required": [
"host",
"userid",
"password"
]
}
}
],
"sourceSpec": {
"name": "CloudStorage",
"type": "CloudStorage",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "input path for copying files, can be a folder path, file path or a wildcard pattern"
},
"recursive": {
"type": "boolean",
"description": "indicates recursive copy in case of folder or wild card path, default is false"
}
},
"required": [
"path"
]
},
"attributes": {
"uiAttributes": {
"documentationLink": "http://www.adobe.com/go/sources-azure-file-storage-en",
"isSource": true,
"category": {
"key": "cloudStorage"
},
"icon": {
"key": "azureFileStorage"
},
"description": {
"key": "azureFileStorageDescription"
},
"label": {
"key": "azureFileStorageLabel"
}
}
}
},
"exploreSpec": {
"name": "FileSystem",
"type": "FileSystem",
"requestSpec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines explorable objects",
"properties": {
"objectType": {
"type": "string",
"enum": [
"file",
"folder",
"root"
]
}
},
"allOf": [
{
"if": {
"properties": {
"objectType": {
"enum": [
"file"
]
}
}
},
"then": {
"properties": {
"object": {
"type": "string",
"description": "defines file to get schema or preview of."
},
"fileType": {
"type": "string",
"enum": [
"delimited"
]
},
"preview": {
"type": "boolean"
}
},
"required": [
"object",
"fileType"
]
}
},
{
"if": {
"properties": {
"objectType": {
"enum": [
"folder"
]
}
}
},
"then": {
"properties": {
"object": {
"type": "string"
}
},
"required": [
"object"
]
}
}
]
},
"responseSpec": {
"root": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "array",
"description": "lists tables/items under the database/container requested.",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "defines type of an item."
},
"name": {
"type": "string",
"description": "defines display name of an item."
},
"path": {
"type": "string",
"description": "defines path of an item."
},
"canPreview": {
"type": "boolean",
"default": false,
"description": "defines whether an item is previewable or not."
},
"canFetchSchema": {
"type": "boolean",
"default": false,
"description": "defines whether schema can be fetched for an item or not."
}
}
}
},
"folder": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"canPreview": {
"type": "boolean",
"default": false
},
"canFetchSchema": {
"type": "boolean",
"default": false
}
}
}
},
"file": {
"delimited": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"format": {
"type": "string"
},
"schema": {
"type": "object",
"properties": {
"columns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
}
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
}
},
"attributes": {
"category": "Cloud Storage",
"connectorName": "Azure File Storage",
"isSource": true,
"isDraftModeSupported": true,
"uiAttributes": {
"apiFeatures": {
"explorePaginationSupported": false
}
}
},
"permissionsInfo": {
"manage": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"write"
]
}
],
"view": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"read"
]
}
]
}
}
]
}
次のリクエストは、クラウドストレージソースのフロー仕様の詳細を取得します。
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name==%22CloudStorageToAEP%22' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
正常な応答は、ソースのフロー仕様情報を返します。ソースでドラフトモードがサポートされているかどうかを確認するには、items[0].attributes.isDraftModeSupported
の値が true
であることを確認します。
{
"items": [
{
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"name": "CloudStorageToAEP",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"sourceConnectionSpecIds": [
"b3ba5556-48be-44b7-8b85-ff2b69b46dc4",
"ecadc60c-7455-4d87-84dc-2a0e293d997b",
"b7829c2f-2eb0-4f49-a6ee-55e33008b629",
"4c10e202-c428-4796-9208-5f1f5732b1cf",
"fb2e94c9-c031-467d-8103-6bd6e0a432f2",
"32e8f412-cdf7-464c-9885-78184cb113fd",
"b7bf2577-4520-42c9-bae9-cad01560f7bc",
"998b8ae3-cec0-43b7-8abe-40b1eb4ee069",
"be5ec48c-5b78-49d5-b8fa-7c89ec4569b8",
"54e221aa-d342-4707-bcff-7a4bceef0001",
"c85f9425-fb21-426c-ad0b-405e9bd8a46c",
"26f526f2-58f4-4712-961d-e41bf1ccc0e8"
],
"targetConnectionSpecIds": [
"c604ff05-7f1a-43c0-8e18-33bf874cb11c"
],
"optionSpec": {
"name": "OptionSpec",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"errorDiagnosticsEnabled": {
"title": "Error diagnostics.",
"description": "Flag to enable detailed and sample error diagnostics summary.",
"type": "boolean",
"default": false
},
"partialIngestionPercent": {
"title": "Partial ingestion threshold.",
"description": "Percentage which defines the threshold of errors allowed before the run is marked as failed.",
"type": "number",
"exclusiveMinimum": 0
}
}
}
},
"transformationSpecs": [
{
"name": "Mapping",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines various params required for different mapping from source to target",
"properties": {
"mappingId": {
"type": "string"
},
"mappingVersion": {
"type": "string"
}
}
}
},
{
"name": "Encryption",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines various params required for encrypted data ingestion",
"properties": {
"publicKeyId": {
"type": "string",
"description": "publicKeyId returned in encryptionKey creation API. One must use the publicKeyId corresponding to the same publicKey they used for encrypting the files"
}
}
}
}
],
"scheduleSpec": {
"name": "PeriodicSchedule",
"type": "Periodic",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"startTime": {
"description": "epoch time",
"type": "integer"
},
"frequency": {
"type": "string",
"enum": [
"once",
"minute",
"hour",
"day",
"week"
]
},
"interval": {
"type": "integer"
},
"backfill": {
"type": "boolean",
"default": true
}
},
"required": [
"startTime",
"frequency"
],
"if": {
"properties": {
"frequency": {
"const": "once"
}
}
},
"then": {
"allOf": [
{
"not": {
"required": [
"interval"
]
}
},
{
"not": {
"required": [
"backfill"
]
}
}
]
},
"else": {
"required": [
"interval"
],
"if": {
"properties": {
"frequency": {
"const": "minute"
}
}
},
"then": {
"properties": {
"interval": {
"minimum": 15
}
}
},
"else": {
"properties": {
"interval": {
"minimum": 1
}
}
}
}
}
},
"attributes": {
"isSourceFlow": true,
"flacValidationSupported": true,
"isDraftModeSupported": true,
"frequency": "batch",
"notification": {
"category": "sources",
"flowRun": {
"enabled": true
}
}
},
"permissionsInfo": {
"manage": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"write"
]
}
],
"view": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"read"
]
}
]
}
}
]
}
ドラフトベース接続を作成するには、Flow Service API の /connections
エンドポイントに対して POST リクエストを実行し、クエリパラメーターとして mode=draft
を指定します。
API 形式
POST /connections?mode=draft
パラメーター | 説明 |
---|---|
mode |
ベース接続の状態を決定するユーザー指定のクエリパラメーター。ベース接続をドラフトとして設定するには、mode を draft に設定します。 |
リクエスト
次のリクエストは、Azure File Storage ソースのドラフトベース接続を作成します。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Azure File Storage Base Connection",
"description": "Azure File Storage base connection for ACME data (DRAFT)",
"auth": {
"specName": "Basic Authentication",
"params": {
"host": "{HOST}",
"userId": "{USER_ID}",
"password": "{PASSWORD}"
}
},
"connectionSpec": {
"id": "be5ec48c-5b78-49d5-b8fa-7c89ec4569b8",
"version": "1.0"
}
}'
応答
正常な応答は、ベース接続 ID と、ドラフトベース接続に対応する etag を返します。後でこの ID を使用して、ベース接続を更新および公開できます。
{
"id": "f9377f50-607a-4818-b77f-50607a181860",
"etag": "\"2f0276fa-0000-0200-0000-5eab3abb0000\""
}
ドラフトを公開する準備が整ったら、/connections
エンドポイントに POST リクエストを実行し、公開するドラフトベース接続の ID と、公開用のアクション操作を指定します。
API 形式
POST /connections/{BASE_CONNECTION_ID}/action?op=publish
パラメーター | 説明 |
---|---|
op |
クエリされたベース接続の状態を更新するアクション操作。ドラフトベース接続を公開するには、op を publish に設定します。 |
リクエスト
次のリクエストは、前の手順で作成した Azure File Storage のドラフトベース接続を公開します。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections/f9377f50-607a-4818-b77f-50607a181860/action?op=publish' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
応答
正常な応答は、ID と、公開されたベース接続に対応する etag を返します。
{
"id": "f9377f50-607a-4818-b77f-50607a181860",
"etag": "\"2f0276fa-0000-0200-0000-5eab3abb0000\""
}
ドラフトソース接続を作成するには、Flow Service API の /sourceConnections
エンドポイントに対して POST リクエストを実行し、クエリパラメーターとして mode=draft
を指定します。
API 形式
POST /sourceConnections?mode=draft
パラメーター | 説明 |
---|---|
mode |
ソース接続の状態を決定するユーザー指定のクエリパラメーター。ソース接続をドラフトとして設定するには、mode を draft に設定します。 |
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections?mode=draft' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Azure File Storage Source Connection",
"description: "Azure File Storage source connection for ACME data (DRAFT)",
"baseConnectionId": "f9377f50-607a-4818-b77f-50607a181860",
"data": {
"format": "delimited",
},
"params": {
"path": "/acme/summerCampaign/account.csv",
"type": "file"
},
"connectionSpec": {
"id": "be5ec48c-5b78-49d5-b8fa-7c89ec4569b8",
"version": "1.0"
}
}'
応答
正常な応答は、ソース接続 ID と、ドラフトソース接続に対応する etag を返します。この ID を後で使用して、ソース接続を更新および公開できます。
{
"id": "26b53912-1005-49f0-b539-12100559f0e2",
"etag": "\"11004d97-0000-0200-0000-5f3c3b140000\""
}
関連付けられたベース接続がまだドラフト状態である場合、ソース接続を公開することはできません。ソース接続を公開する前に、最初にベース接続が公開されていることを確認してください。
ドラフトを公開する準備が整ったら、/sourceConnections
エンドポイントに対して POST リクエストを実行し、公開するドラフトソース接続の ID と公開用のアクション操作を指定します。
API 形式
POST /sourceConnections/{SOURCE_CONNECTION_ID}/action?op=publish
パラメーター | 説明 |
---|---|
op |
クエリされたソース接続の状態を更新するアクション操作。ドラフトソース接続を公開するには、op を publish に設定します。 |
リクエスト
次のリクエストは、前の手順で作成した Azure File Storage のドラフトソース接続を公開します。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections/26b53912-1005-49f0-b539-12100559f0e2/action?op=publish' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
応答
正常な応答は、ID と、公開したソース接続に対応する etag を返します。
{
"id": "26b53912-1005-49f0-b539-12100559f0e2",
"etag": "\"11004d97-0000-0200-0000-5f3c3b140000\""
}
ドラフトターゲット接続を作成するには、Flow Service API の /targetConnections
エンドポイントに対して POST リクエストを実行し、クエリパラメーターとして mode=draft
を指定します。
API 形式
POST /targetConnections?mode=draft
パラメーター | 説明 |
---|---|
mode |
ターゲット接続の状態を決定するユーザー指定のクエリパラメーター。ターゲット接続をドラフトとして設定するには、mode を draft に設定します。 |
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections?mode=draft' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Azure File Storage Target Connection",
"description": "Azure File Storage target connection ACME data (DRAFT)",
"data": {
"schema": {
"id": "{SCHEMA_ID}",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "{DATASET_ID}"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
応答
正常な応答は、ターゲット接続 ID と、ドラフトターゲット接続に対応する etag を返します。この ID を後で使用して、ターゲット接続を更新および公開できます。
{
"id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
関連付けられたベース接続がまだドラフト状態である場合、ターゲット接続を公開することはできません。ターゲット接続を公開する前に、最初にベース接続が公開されていることを確認してください。
ドラフトを公開する準備が整ったら、/targetConnections
エンドポイントに対して POST リクエストを実行し、公開するドラフトターゲット接続の ID と公開用のアクション操作を指定します。
API 形式
POST /targetConnections/{TARGET_CONNECTION_ID}/action?op=publish
パラメーター | 説明 |
---|---|
op |
クエリされたターゲット接続の状態を更新するアクション操作。ドラフトターゲット接続を公開するには、op を publish に設定します。 |
リクエスト
次のリクエストは、前の手順で作成した Azure File Storage のドラフトターゲット接続を公開します。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections/dbc5c132-bc2a-4625-85c1-32bc2a262558/action?op=publish' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
応答
正常な応答は、ID と、公開したターゲット接続に対応する etag を返します。
{
"id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
データフローをドラフトとして設定するには、mode=draft
をクエリパラメーターとして追加したうえで、/flows
エンドポイントに対して POST リクエストを行います。これにより、データフローを作成し、ドラフトとして保存できます。
API 形式
POST /flows?mode=draft
パラメーター | 説明 |
---|---|
mode |
データフローの状態を決定するユーザー指定のクエリパラメーター。データフローをドラフトとして設定するには、mode を draft に設定します。 |
リクエスト
次のリクエストでは、ドラフトデータフローを作成しています。
'https://platform.adobe.io/data/foundation/flowservice/flows?mode=draft' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Azure File Storage Dataflow",
"description": "Azure File Storage dataflow for ACME data (DRAFT)",
"sourceConnectionIds": [
"26b53912-1005-49f0-b539-12100559f0e2"
],
"targetConnectionIds": [
"dbc5c132-bc2a-4625-85c1-32bc2a262558"
],
"flowSpec": {
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"version": "1.0"
}
}'
応答
正常な応答は、フロー ID と、ドラフトデータフローに対応する etag を返します。この ID を後で使用して、データフローを更新および公開できます。
{
"id": "c9751426-dff8-49b0-965f-50defcf4187b",
"etag": "\"69057131-0000-0200-0000-640f48320000\""
}
関連付けられたソース接続とターゲット接続がまだドラフト状態である場合、データフローを公開することはできません。 データフローを公開する前に、最初にソース接続とターゲット接続が公開されていることを確認してください。
ドラフトを公開する準備が整ったら、公開するドラフトデータフローの ID と公開用のアクション操作を指定したうえで、/flows
エンドポイントに対して POST リクエストを行います。
API 形式
POST /flows/{FLOW_ID}/action?op=publish
パラメーター | 説明 |
---|---|
op |
クエリされたデータフローの状態を更新するアクション操作。ドラフトデータフローを公開するには、op を publish に設定します。 |
リクエスト
次のリクエストでは、ドラフトデータフローを公開しています。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows/c9751426-dff8-49b0-965f-50defcf4187b/action?op=publish' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
応答
正常な応答は、データフローの ID と対応する etag
を返します。
{
"id": "c9751426-dff8-49b0-965f-50defcf4187b",
"etag": "\"69057131-0000-0200-0000-640f48320000\""
}
このチュートリアルに従うと、Flow Service エンティティのドラフトを作成し、これらのドラフトを公開する方法を学ぶことができます。ソースについて詳しくは、ソースの概要を参照してください。