資料類型端點

資料類型與基本常值欄位的使用方式相同,可當成類別或混合的參考類型欄位,其主要差異在於資料類型可定義多個子欄位。 雖然與允許一致使用多欄位結構的混音類似,但資料類型更具彈性,因為它們可以包含在架構結構中的任何位置,而混音只能在根層級新增。 Schema Registry API中的/datatypes端點可讓您以程式設計方式管理體驗應用程式中的資料類型。

快速入門

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

檢索資料類型清單

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

注意

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

API格式

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

請求

下列請求會從tenant容器中擷取資料類型清單,使用orderby查詢參數,依其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"
    }
  }
}

查找資料類型

您可以在GET請求的路徑中加入資料類型的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標題。 所有查閱請求都要求version包含在Accept標題中。 以下Accept標題可用:

Accept 標題 說明
application/vnd.adobe.xed+json; version={MAJOR_VERSION} Raw含$refallOf,有標題和說明。
application/vnd.adobe.xed-full+json; version={MAJOR_VERSION} $ref 而且 allOf 有標題和說明。
application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION} Raw含$refallOf,無標題或說明。
application/vnd.adobe.xed-full-notext+json; version={MAJOR_VERSION} $ref 並解 allOf 決,沒有標題或說明。
application/vnd.adobe.xed-full-desc+json; version={MAJOR_VERSION} $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請求以列出租用戶容器中的所有資料類型](#list),現在會包含「屬性詳細資料」資料類型,或者您可以使用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(找不到),因為資料類型已從架構註冊表中移除。

本頁內容