Catalog Service API指南附录

此文档包含帮助您使用Catalog API的其他信息。

视图相关对象

某些Catalog对象可以与其他Catalog对象相关联。 响应有效负荷中由@前缀的任何字段都表示相关对象。 这些字段的值采用URI的形式，URI可在单独的GET请求中使用，以检索它们表示的相关对象。

在查找特定数据集的文档中返回的示例数据集包含具有以下URI值的files字段："@/dataSets/5ba9452f7de80400007fc52a/views/5ba9452f7de80400007fc52b/files"。 files字段的内容可以使用此URI作为新GET请求的路径进行查看。

API格式

GET {OBJECT_URI}

请求

以下请求使用示例数据集的files属性提供的URI来检索数据集关联文件的列表。

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets/5ba9452f7de80400007fc52a/views/5ba9452f7de80400007fc52b/files' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

响应

成功的响应返回相关对象的列表。 在此示例中，返回列表数据集文件。

{
    "7d501090-0280-11ea-a6bb-f18323b7005c-1": {
        "id": "7d501090-0280-11ea-a6bb-f18323b7005c-1",
        "batchId": "7d501090-0280-11ea-a6bb-f18323b7005c",
        "dataSetViewId": "5ba9452f7de80400007fc52b",
        "imsOrg": "{IMS_ORG}",
        "createdUser": "{USER_ID}",
        "createdClient": "{CLIENT_ID}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1573256315368,
        "updated": 1573256315368
    },
    "148ac690-0280-11ea-8d23-8571a35dce49-1": {
        "id": "148ac690-0280-11ea-8d23-8571a35dce49-1",
        "batchId": "148ac690-0280-11ea-8d23-8571a35dce49",
        "dataSetViewId": "5ba9452f7de80400007fc52b",
        "imsOrg": "{IMS_ORG}",
        "createdUser": "{USER_ID}",
        "createdClient": "{CLIENT_ID}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1573255982433,
        "updated": 1573255982433
    },
    "64dd5e19-8ea4-4ddd-acd1-f43cccd8eddb-1": {
        "id": "64dd5e19-8ea4-4ddd-acd1-f43cccd8eddb-1",
        "batchId": "64dd5e19-8ea4-4ddd-acd1-f43cccd8eddb",
        "dataSetViewId": "5ba9452f7de80400007fc52b",
        "imsOrg": "{IMS_ORG}",
        "createdUser": "{USER_ID}",
        "createdClient": "{CLIENT_ID}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1569499425037,
        "updated": 1569499425037
    }
}

在一次呼叫中发出多个请求

Catalog API的根端点允许在单个调用中发出多个请求。 请求有效负荷包含表示通常是单个请求的对象的数组，然后按顺序执行。

如果这些请求是对Catalog的修改或添加，并且任何一项更改都失败，则所有更改都将恢复。

API格式

POST /

请求

以下请求会创建新数据集，然后为该数据集创建相关视图。 此示例演示如何使用模板语言访问先前调用中返回的值，以便在后续调用中使用。

例如，如果要引用从以前的子请求返回的值，则可以创建以下格式的引用：<<{REQUEST_ID}.{ATTRIBUTE_NAME}>>（其中{REQUEST_ID}是用户为子请求提供的ID，如下所示）。 您可以使用这些模板来引用先前子请求响应对象正文中可用的任何属性。

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": "firstObjectId",
      "resource": "/dataSets",
      "method": "post",
      "body": {
        "type": "raw",
        "name": "First Dataset"
      }
    }, 
    {
      "id": "secondObjectId",
      "resource": "/datasetViews",
      "method": "post",
      "body": {
        "status": "enabled",
        "dataSetId": "<<firstObjectId.id>>"
      }
    }
  ]'

响应

成功的响应返回一组对象，这些对象包含您分配给每个请求的id、单个请求的HTTP状态代码和响应body。 由于三个示例请求都是为创建新对象而发出的，因此每个对象的body都是一个仅包含新创建对象ID的数组，同Catalog中POST响应最成功的标准一样。

[
    {
        "id": "firstObjectId",
        "code": 200,
        "body": [
            "@/dataSets/5be230aef5b02914cd52dbfa"
        ]
    },
    {
        "id": "secondObjectId",
        "code": 200,
        "body": [
            "@/dataSetViews/5be230aef5b02914cd52dbfb"
        ]
    }
]

检查对多个请求的响应时要小心，因为您需要验证每个单个子请求的代码，而不是只依赖父POST请求的HTTP状态代码。 单个子请求可返回404(例如对无效资源的GET请求)，而总请求返回200。

其他请求标头

Catalog 提供了多种标题约定，帮助您在更新过程中保持数据的完整性。

If-Match

最好使用对象版本控制来防止在多个用户几乎同时保存对象时发生的数据损坏类型。

更新对象时的最佳实践是首先对要更新的对象进行API调用视图(GET)。 包含在响应中（以及响应包含单个对象的任何调用）是包含该对象版本的E-Tag头。 在更新(PUT或PATCH)调用中将对象版本添加为名为If-Match的请求标头，将导致更新仅在版本仍然相同的情况下才成功，从而有助于防止数据冲突。

如果版本不匹配（自您检索到该对象后，该对象被其他进程修改），您将收到HTTP状态412（先决条件失败），表示已拒绝访问目标资源。

Pragma

有时，您可能希望验证对象而不保存信息。 使用值为validate-only的Pragma头，您只能发送POST或PUT请求以用于验证目的，从而防止对数据所做的任何更改被保留。

数据压缩

压缩是一种Experience Platform服务，可将小文件中的数据合并到大文件中，而不更改任何数据。 出于性能原因，有时将一组小文件合并为较大的文件，以便在查询时能够更快地访问数据。

当摄取的批次中的文件已压缩时，其关联的Catalog对象将更新以用于监视目的。