資料類型與基本常值欄位的使用方式相同,可當成類別或混合的參考類型欄位,其主要差異在於資料類型可定義多個子欄位。 雖然與允許一致使用多欄位結構的混音類似,但資料類型更具彈性,因為它們可以包含在架構結構中的任何位置,而混音只能在根層級新增。 Schema Registry API中的/datatypes
端點可讓您以程式設計方式管理體驗應用程式中的資料類型。
本指南中使用的端點是Schema Registry API的一部分。 在繼續之前,請先閱讀快速入門手冊,以取得相關檔案的連結、閱讀本檔案中範例API呼叫的指南,以及成功呼叫任何Experience Platform API所需之必要標題的重要資訊。
您可以分別對/global/datatypes
或/tenant/datatypes
發出GET請求,以列出global
或tenant
容器下的所有資料類型。
列出資源時,方案註冊表將結果集限制為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資料類型,並包含原始的$ref 和allOf 。 (限制:300) |
回應
上述請求使用application/vnd.adobe.xed-id+json
Accept
標題,因此回應僅包含每個資料類型的title
、$id
、meta:altId
和version
屬性。 使用其他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含$ref 和allOf ,有標題和說明。 |
application/vnd.adobe.xed-full+json; version={MAJOR_VERSION} |
$ref 而且 allOf 有標題和說明。 |
application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION} |
Raw含$ref 和allOf ,無標題或說明。 |
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:extends
或meta: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(已建立)和包含新建立之資料類型詳細資料的裝載,包括$id
、meta:altId
和version
。 這三個值是只讀的,由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修補程式作業,包括add
、remove
和replace
。 如需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(找不到),因為資料類型已從架構註冊表中移除。