Show Menu
トピック×

セグメント定義エンドポイント

Adobe Experience Platform を使用すると、プロファイルのグループから特定の属性やビヘイビアーのグループを定義するセグメントを作成できます。A segment definition is an object that encapsulates a query written in Profile Query Language (PQL). このオブジェクトは PQL 述語とも呼ばれます。PQL predicates define the rules for the segment based on conditions related to any record or time-series data you supply to Real-time Customer Profile. PQL クエリの記述について詳しくは、 PQL ガイド を参照してください。
このガイドは、セグメント定義をより深く理解するのに役立つ情報を提供し、APIを使用して基本的なアクションを実行するためのサンプルAPI呼び出しを含みます。

はじめに

The endpoints used in this guide are part of the Adobe Experience Platform Segmentation Service API. Before continuing, please review the getting started guide for important information that you need to know in order to successfully make calls to the API, including required headers and how to read example API calls.

セグメント定義のリストの取得

IMS 組織の全セグメント定義のリストを取得するには、 /segment/definitions エンドポイントへの GET リクエストを実行します。
API 形式
エンドポイントでは、結果のフィルタリングに役立ついくつかのクエリパラメーターが /segment/definitions サポートされています。 これらのパラメーターはオプションですが、高価なオーバーヘッドを削減するために、このパラメーターの使用を強くお勧めします。 パラメーターを指定しないでこのエンドポイントに呼び出しを実行すると、組織で使用可能なセグメント定義がすべて取得されます。複数のパラメーターを使用する場合は、アンパサンド( & )で区切ります。
GET /segment/definitions
GET /segment/definitions?{QUERY_PARAMETERS}

クエリパラメータ
パラメーター
説明
start
返されるセグメント定義の開始オフセットを指定します。
start=4
limit
返される、1 ページあたりのセグメント定義の数を指定します。
limit=20
page
どのページからセグメント定義の結果を表示するかを指定します。
page=5
sort
結果を並べ替える基準となるフィールドを指定します。 Is written in the following format: [attributeName]:[desc|asc] .
sort=updateTime:desc
evaluationInfo.continuous.enabled
セグメント定義でストリーミングを有効にするかどうかを指定します。
evaluationInfo.continuous.enabled=true
リクエスト
次のリクエストは、IMS組織内で投稿された最後の2つのセグメント定義を取得します。
curl -X GET https://platform.adobe.io/data/core/ups/segment/definitions?limit=2 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

応答
リクエストが成功した場合は、指定した IMS 組織のセグメント定義のリスト(JSON 形式)と HTTP ステータス 200 が返されます。
{
    "segments": [
        {
            "id": "3da8bad9-29fb-40e0-b39e-f80322e964de",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{IMS_ORG}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "segment",
            "description": "",
            "expression": {
                "type": "PQL",
                "format": "pql/json",
                "value": "{PQL_EXPRESSION}"
            },
            "mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 1573253640000,
            "baselineTime": 1574327114,
            "updateEpoch": 1575588309,
            "updateTime": 1575588309000
        },
        {
            "id": "ca763983-5572-4ea4-809c-b7dff7e0d79b",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{IMS_ORG}",
            "name": "test segment",
            "description": "",
            "expression": {
                "type": "PQL",
                "format": "pql/json",
                "value": "{PQL_EXPRESSION}"
            },
            "mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 1561073779000,
            "baselineTime": 1574327114,
            "updateEpoch": 1574327114,
            "updateTime": 1574327114000
        }
    ],
    "page": {
        "totalCount": 2,
        "totalPages": 1,
        "sortField": "creationTime",
        "sort": "desc",
        "pageSize": 2,
        "limit": 100
    },
    "link": {}
}

新しいセグメント定義の作成

新しいセグメント定義を作成するには、 /segment/definitions エンドポイントに POST リクエストを実行します。
API 形式
POST /segment/definitions

リクエスト
curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "People who ordered in the last 30 days",
        "profileInstanceId": "ups",
        "description": "Last 30 days",
        "expression": {
            "type": "PQL",
            "format": "pql/text",
            "value": "workAddress.country = \"US\""
        },
        "schema": {
            "name": "_xdm.context.profile"
        },
        "payloadSchema": "string",
        "ttlInDays": 60
    }'

プロパティ
説明
name
必須 。セグメントを参照する際に使用される一意の名前です。
schema
必須 。セグメント内のエンティティに関連付けられているスキーマです。 id name のどちらかのフィールドで構成されます。
expression
必須 。セグメント定義に関するフィールド情報を含んだエンティティです。
expression.type
式タイプを指定します。現時点では、「PQL」のみサポートされています。
expression.format
値内の式の構造を示します。現時点では、次の形式がサポートされています。
  • pql/text :セグメント定義のテキスト表現で、公開された PQL 文法に従っている必要があります。例: workAddress.stateProvince = homeAddress.stateProvince
expression.value
expression.format に指定されたタイプに適合する式です。
description
定義の人間が読み取り可能な説明。
応答
リクエストが成功した場合は、新しく作成したセグメント定義の詳細と HTTP ステータス 200 が返されます。
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "People who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"US\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579292094,
    "updateTime": 1579292094000
}

プロパティ
説明
id
新しく作成されたセグメント定義のシステム生成ID。
evaluationInfo
セグメント定義が受ける評価のタイプを示す、システム生成オブジェクト。 バッチ、連続(ストリーミング)または同期セグメントを使用できます。

特定のセグメント定義の取得

You can retrieve detailed information about a specific segment definition by making a GET request to the /segment/definitions endpoint and providing the ID of the segment definition you wish to retrieve in the request path.
API 形式
GET /segment/definitions/{SEGMENT_ID}

パラメーター
説明
{SEGMENT_ID}
The id value of the segment definition you want to retrieve.
リクエスト
curl -X GET https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

応答
リクエストが成功した場合は、特定のセグメント定義についての詳細情報と HTTP ステータス 200 が返されます。
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "People who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"US\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579292094,
    "updateTime": 1579292094000
}

プロパティ
説明
id
システム生成のセグメント定義の読み取り専用ID。
name
。セグメントを参照する際に使用される一意の名前です。
schema
。セグメント内のエンティティに関連付けられているスキーマです。 id name のどちらかのフィールドで構成されます。
expression
。セグメント定義に関するフィールド情報を含んだエンティティです。
expression.type
式タイプを指定します。現時点では、「PQL」のみサポートされています。
expression.format
値内の式の構造を示します。現時点では、次の形式がサポートされています。
  • pql/text :セグメント定義のテキスト表現で、公開された PQL 文法に従っている必要があります。例: workAddress.stateProvince = homeAddress.stateProvince
expression.value
expression.format に指定されたタイプに適合する式です。
description
人間にとってわかりやすい、定義の説明。
evaluationInfo
システム生成オブジェクト。評価、バッチ、連続(ストリーミングとも呼ばれます)または同期のタイプを指定し、セグメント定義が実行されます。

一括取得セグメント定義

エンドポイントにPOSTリクエストを送信し、リクエスト本文にセグメント定義の /segment/definitions/bulk-get id 値を入力することで、指定した複数のセグメント定義に関する詳細な情報を取得できます。
API 形式
POST /segment/definitions/bulk-get

リクエスト
curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions/bulk-get \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "ids": [
            {
                "id": "54669488-03ab-4e0d-a694-37fe49e32be8"
            },
            {
                "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05"
            }
        ]
    }'

応答  
正常な応答が返されると、HTTPステータス207が返され、このステータスには要求されたセグメント定義が含まれます。
{
    "results": {
        "54669488-03ab-4e0d-a694-37fe49e32be8": {
            "id": "54669488-03ab-4e0d-a694-37fe49e32be8",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 60,
            "profileInstanceId": "ups",
            "imsOrgId": "{IMS_ORG}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "People who ordered in the last 30 days",
            "description": "Last 30 days",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "workAddress.country = \"US\""
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 0,
            "updateEpoch": 1579292094,
            "updateTime": 1579292094000
        },
        "4afe34ae-8c98-4513-8a1d-67ccaa54bc05": {
            "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 60,
            "profileInstanceId": "ups",
            "imsOrgId": "{IMS_ORG}",
            "sandbox": {
                "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
                "sandboxName": "prod",
                "type": "production",
                "default": true
            },
            "name": "People who ordered in the last 30 days",
            "description": "Last 30 days",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "workAddress.country = \"US\""
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": false
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "dataGovernancePolicy": {
                "excludeOptOut": true
            },
            "creationTime": 0,
            "updateEpoch": 1579292094,
            "updateTime": 1579292094000
        }

    }
}

プロパティ
説明
id
システム生成のセグメント定義の読み取り専用ID。
name
。セグメントを参照する際に使用される一意の名前です。
schema
。セグメント内のエンティティに関連付けられているスキーマです。 id name のどちらかのフィールドで構成されます。
expression
。セグメント定義に関するフィールド情報を含んだエンティティです。
expression.type
式タイプを指定します。現時点では、「PQL」のみサポートされています。
expression.format
値内の式の構造を示します。現時点では、次の形式がサポートされています。
  • pql/text :セグメント定義のテキスト表現で、公開された PQL 文法に従っている必要があります。例: workAddress.stateProvince = homeAddress.stateProvince
expression.value
expression.format に指定されたタイプに適合する式です。
description
人間にとってわかりやすい、定義の説明。
evaluationInfo
システム生成オブジェクト。評価、バッチ、連続(ストリーミングとも呼ばれます)または同期のタイプを指定し、セグメント定義が実行されます。

特定のセグメント定義の削除

You can request to delete a specific segment definition by making a DELETE request to the /segment/definitions endpoint and providing the ID of the segment definition you wish to delete in the request path.
API 形式
DELETE /segment/definitions/{SEGMENT_ID}

パラメーター
説明
{SEGMENT_ID}
:削除するセグメント定義の id 値。
リクエスト
curl -X DELETE https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

応答
リクエストが成功した場合、HTTP ステータス 200 が返され、メッセージは返されません。

特定のセグメント定義の更新

エンドポイントにPATCHリクエストを送信し、更新するセグメント定義のIDをリクエストパスに指定することで、特定のセグメント定義を更新でき /segment/definitions ます。
API 形式
PATCH /segment/definitions/{SEGMENT_ID}

パラメーター
説明
{SEGMENT_ID}
The id value of the segment definition you want to update.
リクエスト
次のリクエストは、米国からカナダへの勤務先住所の国の更新を求めています。
curl -X PATCH https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "name": "Updated people who ordered in the last 30 days",
    "profileInstanceId": "ups",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"CA\""
    },
    "schema": {
        "name": "_xdm.context.profile"
    },
    "payloadSchema": "string",
    "ttlInDays": 60,
    "creationTime": 0,
    "updateTime": 0,
    "updateEpoch": 0
}'

応答  
リクエストが成功した場合は、更新したセグメント定義の詳細と HTTP ステータス 200 が返されます。勤務先住所の国が米国からカナダ(CA)に更新されたことに注目してください。
{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "Updated people who ordered in the last 30 days",
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "workAddress.country = \"CA\""
    },
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "dataGovernancePolicy": {
        "excludeOptOut": true
    },
    "creationTime": 0,
    "updateEpoch": 1579295340,
    "updateTime": 1579295340000
}

次の手順

このガイドを読むと、セグメント定義の動作についての理解が深まります。 セグメントの作成の詳細については、「セグメントの 作成 」チュートリアルを参照してください。