資料類型端點

在類或方案欄位組中,資料類型與基本常值欄位的使用方式相同,其關鍵區別在於資料類型可以定義多個子欄位。 雖然與中的欄位組類似,它們允許一致地使用多欄位結構,但資料類型更靈活,因為它們可以包含在架構結構中的任何位置,而欄位組只能在根級別添加。 Schema Registry API中的/datatypes端點可讓您以程式設計方式管理體驗應用程式中的資料類型。

快速入門

本指南中使用的端點是Schema Registry API的一部分。 繼續之前,請檢閱快速入門手冊,取得相關檔案的連結、閱讀本檔案中範例API呼叫的指南,以及成功呼叫任何Experience PlatformAPI所需的必要標頭的重要資訊。

擷取資料類型清單

您可以分別向/global/datatypes/tenant/datatypes發出GET請求,以列出globaltenant容器下的所有資料類型。

注意

列出資源時,方案註冊表將結果集限制為300個項。 若要傳回超過此限制的資源,您必須使用分頁參數。 建議您使用其他查詢參數來篩選結果並減少傳回的資源數。 如需詳細資訊,請參閱附錄檔案中查詢參數一節。

API格式

GET /{CONTAINER_ID}/datatypes?{QUERY_PARAMS}
參數 說明
{CONTAINER_ID} 您要從中擷取資料類型的容器:global適用於Adobe建立的資料類型,或tenant適用於您組織擁有的資料類型。
{QUERY_PARAMS} 可選的查詢參數,以依據篩選結果。 有關可用參數的清單,請參見附錄文檔

要求

下列請求會使用orderby查詢參數,從tenant容器中擷取資料類型清單,以依據其title屬性來排序資料類型。

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes?orderby=title \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -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}'

回應格式取決於要求中傳送的Accept標題。 下列Accept標題可用於列出資料類型:

Accept 標題 說明
application/vnd.adobe.xed-id+json 傳回每個資源的簡短摘要。 這是列出資源的建議標題。 (限制:300)
application/vnd.adobe.xed+json 傳回每個資源的完整JSON資料類型,並包含原始的$refallOf。 (限制:300)

回應

上述請求使用application/vnd.adobe.xed-id+json Accept標題,因此回應僅包含每個資料類型的title$idmeta:altIdversion屬性。 使用其他Accept標題(application/vnd.adobe.xed+json)會傳回每個資料類型的所有屬性。 根據您在回應中需要的資訊,選取適當的Accept標題。

{
  "results": [
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/78570e371092c032260714dd8bfd6d44",
      "meta:altId": "_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44",
      "version": "1.0",
      "title": "Loyalty"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/4b0329b5573cbb7cb757db667d7fdf66",
      "meta:altId": "_{TENANT_ID}.datatypes.4b0329b5573cbb7cb757db667d7fdf66",
      "version": "1.0",
      "title": "Property Details"
    }
  ],
  "_page": {
    "orderby": "title",
    "next": null,
    "count": 2
  },
  "_links": {
    "next": null,
    "global_schemas": {
      "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/datatypes?orderby=title"
    }
  }
}

查詢資料類型

您可以在請求的路徑中加入資料類型的ID,以查詢特定資料類型。

API格式

GET /{CONTAINER_ID}/datatypes/{DATA_TYPE_ID}
參數 說明
{CONTAINER_ID} 儲存您要擷取之資料類型的容器:global適用於Adobe建立的資料類型,或tenant適用於貴組織擁有的資料類型。
{DATA_TYPE_ID} 要查詢的資料類型的meta:altId或URL編碼的$id

要求

下列請求會依路徑中提供的meta:altId值擷取資料類型。

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44 \
  -H 'Accept: application/vnd.adobe.xed+json' \
  -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}'

回應格式取決於要求中傳送的Accept標題。 所有查詢請求都需要在Accept標題中包含version。 可使用下列Accept標題:

Accept 標題 說明
application/vnd.adobe.xed+json; version=1 具有$refallOf的原始檔案具有標題和說明。
application/vnd.adobe.xed-full+json; version=1 $refallOf 已解析,有標題和說明。
application/vnd.adobe.xed-notext+json; version=1 原始格式包含$refallOf,沒有標題或說明。
application/vnd.adobe.xed-full-notext+json; version=1 $refallOf 解析,沒有標題或說明。
application/vnd.adobe.xed-full-desc+json; version=1 $ref 和已 allOf 解析的描述符。

回應

成功的回應會傳回資料類型的詳細資訊。 傳回的欄位取決於請求中傳送的Accept標題。 請試驗不同的Accept標題,比較回應並判斷哪個標題最適合您的使用案例。

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/78570e371092c032260714dd8bfd6d44",
  "meta:altId": "_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Loyalty",
  "type": "object",
  "description": "Loyalty object containing loyalty-specific fields.",
  "definitions": {
    "customFields": {
      "properties": {
        "loyaltyId": {
          "title": "Loyalty ID",
          "description": "Unique loyalty program member ID. Should be in the format of an email address.",
          "type": "string",
          "meta:xdmType": "string"
        },
        "memberSince": {
          "title": "Member Since",
          "description": "Date person joined loyalty program.",
          "type": "string",
          "format": "date",
          "meta:xdmType": "date"
        },
        "points": {
          "title": "Points",
          "description": "Accumulated loyalty points",
          "type": "integer",
          "meta:xdmType": "int"
        },
        "loyaltyLevel": {
          "title": "Loyalty Level",
          "description": "The current loyalty program level to which the individual member belongs.",
          "type": "string",
          "enum": [
            "platinum",
            "gold",
            "silver",
            "bronze"
          ],
          "meta:enum": {
            "platinum": "Platinum",
            "gold": "Gold",
            "silver": "Silver",
            "bronze": "Bronze"
          },
          "meta:xdmType": "string"
        }
      },
      "type": "object",
      "meta:xdmType": "object"
    }
  },
  "allOf": [
    {
      "$ref": "#/definitions/customFields"
    }
  ],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1557529442681,
    "repo:lastModifiedDate": 1557529442681,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "50b8008b588e911314f9685240dd4c23a247f37179a6d9ff6ba3877dc11ca504",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

建立資料類型

您可以提出POST要求,在tenant容器下定義自訂資料類型。

API格式

POST /tenant/datatypes

要求

定義資料類型不需要meta:extendsmeta:intendedToExtend欄位,也不需要巢狀欄位以避免衝突。

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title":"Property Construction",
        "description":"Information related to the property construction",
        "type":"object",
        "properties": {
          "yearBuilt": {
            "type":"integer",
            "title": "Year Built",
            "description": "The year the property was constructed."
          },
          "propertyType": {
            "type":"string",
            "title": "Property Type",
            "description": "Type of building or structure in which the property exists.",
            "enum": [
              "freeStanding",
              "mall",
              "shoppingCenter"
            ],
            "meta:enum": {
              "freeStanding": "Free Standing Building",
              "mall": "Mall Space",
              "shoppingCenter": "Shopping Center"
            }
          }
        } 
      }'

回應

成功的回應會傳回HTTP狀態201(已建立),以及包含新建立資料類型詳細資訊的裝載,包括$idmeta:altIdversion。 這三個值為唯讀值,由Schema Registry指派。

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:altId": "_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Property Construction",
  "type": "object",
  "description": "Information related to the property construction",
  "properties": {
    "yearBuilt": {
      "type": "integer",
      "title": "Year Built",
      "description": "The year the property was constructed.",
      "meta:xdmType": "int"
    },
    "propertyType": {
      "type": "string",
      "title": "Property Type",
      "description": "Type of building or structure in which the property exists.",
      "enum": [
        "freeStanding",
        "mall",
        "shoppingCenter"
      ],
      "meta:enum": {
        "freeStanding": "Free Standing Building",
        "mall": "Mall Space",
        "shoppingCenter": "Shopping Center"
      },
      "meta:xdmType": "string"
    }
  },
  "refs": [],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1604524729435,
    "repo:lastModifiedDate": 1604524729435,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "1c838764342756868ca1297869f582a38d15f03ed0acfc97fda7532d22e942c7",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

在租用戶容器中執行GET請求以列出所有資料類型現在將包含「屬性詳細資料」資料類型,或者,您可以使用URL編碼的$id URI執行查詢(GET)請求以直接查看新資料類型。

更新資料類型

您可以透過PUT操作取代整個資料類型,實際上是重新寫入資源。 透過PUT請求更新資料類型時,內文必須包含在POST請求中建立新資料類型時所需的所有欄位。

注意

如果您只想更新部分資料類型而非完全替換,請參閱上更新部分資料類型的部分。

API格式

PUT /tenant/datatypes/{DATA_TYPE_ID}
參數 說明
{DATA_TYPE_ID} 要重寫的資料類型的meta:altId或URL編碼的$id

要求

下列請求會重新寫入現有的資料類型,並新增floorSize欄位。

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title": "Property Construction",
        "description": "Information related to the property construction",
        "type": "object",
        "properties": {
          "yearBuilt": {
            "type":"integer",
            "title": "Year Built",
            "description": "The year the property was constructed."
          },
          "propertyType": {
            "type":"string",
            "title": "Property Type",
            "description": "Type of building or structure in which the property exists.",
            "enum": [
              "freeStanding",
              "mall",
              "shoppingCenter"
            ],
            "meta:enum": {
              "freeStanding": "Free Standing Building",
              "mall": "Mall Space",
              "shoppingCenter": "Shopping Center"
            }
          },
          "floorSize" {
            "type": "integer",
            "title": "Floor Size",
            "description": "The floor size of the property, in square feet."
          }
        } 
      }'

回應

成功的回應會傳回更新資料類型的詳細資訊。

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:altId": "_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Property Construction",
  "type": "object",
  "description": "Information related to the property construction",
  "properties": {
    "yearBuilt": {
      "type": "integer",
      "title": "Year Built",
      "description": "The year the property was constructed.",
      "meta:xdmType": "int"
    },
    "propertyType": {
      "type": "string",
      "title": "Property Type",
      "description": "Type of building or structure in which the property exists.",
      "enum": [
        "freeStanding",
        "mall",
        "shoppingCenter"
      ],
      "meta:enum": {
        "freeStanding": "Free Standing Building",
        "mall": "Mall Space",
        "shoppingCenter": "Shopping Center"
      },
      "meta:xdmType": "string"
    },
    "floorSize" {
      "type":  "integer",
      "title":  "Floor Size",
      "description":  "The floor size of the property, in square feet.",
      "meta:xdmType": "int"
    }
  },
  "refs": [],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1604524729435,
    "repo:lastModifiedDate": 1604524729435,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "1c838764342756868ca1297869f582a38d15f03ed0acfc97fda7532d22e942c7",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

更新資料類型的一部分

您可以使用PATCH請求來更新部分資料類型。 Schema Registry支援所有標準JSON修補程式操作,包括addremovereplace。 如需JSON修補程式的詳細資訊,請參閱API基礎指南

注意

如果您想用新值取代整個資源,而不是更新個別欄位,請參閱上的區段,使用PUT操作取代資料類型。

API格式

PATCH /tenant/data type/{DATA_TYPE_ID} 
參數 說明
{DATA_TYPE_ID} 要更新的資料類型的URL編碼的$id URI或meta:altId

要求

以下範例要求會更新現有資料類型的description,並新增一個floorSize欄位。

要求內文採用陣列的形式,每個列出的物件代表個別欄位的特定變更。 每個對象包括要執行的操作(op),該操作應在哪個欄位(path)上執行,以及該操作應包括哪些資訊(value)。

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
  -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 '[
        {
          "op": "replace",
          "path": "/description",
          "value": "Construction-related information for a company-operated property."
        },
        { 
          "op": "add",
          "path": "/properties/floorSize",
          "value": {
            "type": "integer",
            "title": "Floor Size",
            "description": "The floor size of the property, in square feet."
          }
        }
      ]'

回應

響應顯示兩個操作均已成功執行。 description已更新,而floorSize已新增至definitions下。

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/8779fd45d6e4eb074300023a439862bbba359b60d451627a",
  "meta:altId": "_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a",
  "meta:resourceType": "datatypes",
  "version": "1.2",
  "title": "Property Details",
  "type": "object",
  "description": "Details relating to a property operated by the company.",
  "definitions": {
    "property": {
      "properties": {
        "_{TENANT_ID}": {
        "type":"object",
        "properties": {
            "propertyName": {
              "type": "string",
              "title": "Property Name",
              "description": "Name of the property"
            },
            "propertyCity": {
              "title": "Property City",
              "description": "City where the property is located.",
              "type": "string"
            },
            "propertyCountry": {
              "title": "Property Country",
              "description": "Country where the property is located.",
              "type": "string"
            },
            "phoneNumber": {
              "title": "Phone Number",
              "description": "Primary phone number for the property.",
              "type": "string"
            },
            "propertyType": {
              "type": "string",
              "title": "Property Type",
              "description": "Type and primary use of property.",
              "enum": [
                  "retail",
                  "yoga",
                  "fitness"
              ],
              "meta:enum": {
                  "retail": "Retail Store",
                  "yoga": "Yoga Studio",
                  "fitness": "Fitness Center"
              }
            },
            "propertyConstruction": {
              "$ref": "https://ns.adobe.com/{TENANT_ID}/datatypes/24c643f618647344606222c494bd0102"
            }
          }
        }
      }
    }
  },
  "allOf": [
    {
      "$ref": "#/definitions/customFields",
      "type": "object",
      "meta:xdmType": "object"
    }
  ],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:intendedToExtend": [
    "https://ns.adobe.com/xdm/context/profile"
  ],
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1594941263588,
    "repo:lastModifiedDate": 1594941538433,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "5e8a5e508eb2ed344c08cb23ed27cfb60c841bec59a2f7513deda0f7af903021",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

刪除資料類型

有時可能需要從架構註冊表中刪除資料類型。 若要這麼做,請使用路徑中提供的資料類型ID執行DELETE要求。

API格式

DELETE /tenant/datatypes/{DATA_TYPE_ID}
參數 說明
{DATA_TYPE_ID} 要刪除的資料類型的URL編碼的$id URI或meta:altId

要求

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.d5cc04eb8d50190001287e4c869ebe67 \
  -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}'

回應

成功的回應會傳回HTTP狀態204(無內容)和空白內文。

您可以嘗試將查詢(GET)請求嘗試刪除資料類型,以確認刪除。 您需要在請求中加入Accept標題,但應該會收到HTTP狀態404(找不到),因為資料類型已從架構註冊表中移除。

本頁內容