(選擇性) 建立結構描述 (進階使用者) - AWS Clean Rooms
對映和位置表格資料架構

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

(選擇性) 建立結構描述 (進階使用者)

手動建立結構描述適用於進階使用者。

以下是包含或不含欄標題之輸入檔案的JSON結構描述檔案格式。如果需要，高級用戶可以直接編寫或修改模式。

注意

C3R 加密客戶端可以幫助您通過中描述的互動過程範例：使用sealed、fingerprint和cleartext欄產生加密綱要或通過創建存根模板來創建模式。

對映和位置表格資料架構

下節說明兩種資料表結構定義：

  • 對應資料表結構描述 — 此結構描述用於使用標題列和Apache Parquet檔案加密 .csv 檔案。

  • 位置資料表結構描述 — 此結構描述用於加密沒有標題列的 .csv 檔案。

C3R 加密客戶端可以加密表格文件以進行協作。要做到這一點，它必須有一個對應的結構描述文件，該文件指定如何從輸入導出加密輸出。

C3R 加密用戶端可以在命令列上執行 C3R 加密用戶端結構描述命令，協助產生INPUT檔案的結構描述。命令的一個例子是java -jar c3r-cli.jar schema --interactive INPUT。

結構描述會指定下列資訊：

  1. 來源欄對映至哪些來源欄，透過其標頭名稱 (對映的結構描述) 或位置 (位置資料架構) 轉換輸出檔案中的欄

  2. 要保留哪些目標資料欄 cleartext

  3. 要針對SELECT查詢加密的目標資料欄

  4. 要針對JOIN查詢加密的目標資料欄

此資訊會以資料表特定的JSON結構描述檔案編碼，該檔案由headerRow欄位為布林值的單一物件組成。該值必須true適用於Parquet具有標題列的檔案和 .csv 檔案，false否則。

對映資料表結構

對映的結構描述具有以下形狀。

{
  "headerRow": true,
  "columns": [
    {
      "sourceHeader": STRING,
      "targetHeader": STRING,
      "type": TYPE,
      "pad": PAD
    },
    ...
  ]
}

如果headerRow是true，則物件中的下一個欄位是columns，其中包含將來源標頭對應至目標標頭的資料行結構描述陣列 (也就是說明輸出資料行應包含的JSON物件)。

  • sourceHeader— 資料衍生自之來源資料行的STRING標頭名稱。

    注意

    相同的來源資料欄可用於多個目標資料欄。

    輸出檔案中未列為結構定義中sourceHeader任何位置的輸入檔案中的資料行不會顯示在輸出檔案中。

  • targetHeader— 輸出檔案中對應欄的STRING標頭名稱。

    注意

    對於對應的綱要，此欄位是選擇性的。如果省略此欄位，sourceHeader則會重新用於輸出中的標頭名稱。如果輸出資料行分別為欄或fingerprintsealed欄，則會附加或。_fingerprint _sealed

  • type— 輸TYPE出檔案中目標欄的。也就是說，其中之一 cleartextsealed，或fingerprint取決於在協同作業中使用欄的方式。

  • pad— 資料行結構描述物件的欄位，只有在是時才會TYPE出現sealed。的對應值PAD是描述資料在加密之前應如何填充資料的物件。

    {
  "type": PAD_TYPE,
  "length": INT
}

    要指定預加密填充，type並length使用如下：

    • PAD_TYPEas none-不填充將應用於列的數據，並且該length字段不適用（也就是省略）。

    • PAD_TYPEas fixed — 資料行的資料會填補至指定length的位元組。

    • PAD_TYPEas max — 資料行的資料會填補至最長值的位元組長度加上一個額外length位元組的大小。

以下是對應結構描述的範例，其中包含每種類型的資料行。

{
  "headerRow": true,
  "columns": [
    {
      "sourceHeader": "FullName",
      "targetHeader": "name",
      "type": "cleartext"
    },
    {
      "sourceHeader": "City",
      "targetHeader": "city_sealed",
      "type": "sealed",
      "pad": {
        "type": "max",
        "length": 16
      }
    },
    {
      "sourceHeader": "PhoneNumber",
      "targetHeader": "phone_number_fingerprint",
      "type": "fingerprint"
    },
    {
      "sourceHeader": "PhoneNumber",
      "targetHeader": "phone_number_sealed",
      "type": "sealed",
      "pad": {
        "type": "fixed",
        "length": 20
      }
    }
  ]
}

以下是一個更複雜的範例，以下是包含標題的 .csv 檔案範例。

FirstName,LastName,Address,City,State,PhoneNumber,Title,Level,Notes
Jorge,Souza,12345 Mills Rd,Anytown,SC,703-555-1234,CEO,10,
Paulo,Santos,0 Street,Anytown,MD,404-555-111,CIO,9,This is a really long note that could really be a paragraph
Mateo,Jackson,1 Two St,Anytown,NY,304-555-1324,COO,9,""
Terry,Whitlock4 N St,Anytown,VA,407-555-8888,EA,7,Secret notes
Diego,Ramirez,9 Hollows Rd,Anytown,VA,407-555-1222,SDE I,4,null
John,Doe,8 Hollows Rd,Anytown,VA,407-555-4321,SDE I,4,Jane's younger brother
Jane,Doe,8 Hollows Rd,Anytown,VA,407-555-4322,SDE II,5,John's older sister

在下列對應的結構描述範例中，資料LastName行FirstName和cleartext欄。資State料行會加密為fingerprint資料行，以及填補為的sealed欄none。其餘的列被省略。

{
  "headerRow": true,
  "columns": [
    {
      "sourceHeader": "FirstName",
      "targetHeader": "GivenName",
      "type": "cleartext"
    },
    {
      "sourceHeader": "LastName",
      "targetHeader": "Surname",
      "type": "cleartext"
    },
    {
      "sourceHeader": "State",
      "targetHeader": "State_Join",
      "type": "fingerprint"
    },
    {
      "sourceHeader": "State",
      "targetHeader": "State",
      "type": "sealed",
      "pad": {
        "type": "none"
      }
    }
  ]
}

以下是由對應結構描述產生的 .csv 檔案。

givenname,surname,state_fingerprint,state
John,Doe,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:FQ3n3Ahv9BQQNWQGcugeHzHYzEZE1vapHa2Uu4SRgSAtZ3qObjPA4TcsHt+BOkMKBcnHWI13BeGG/SBqmj7vKpI=
Paulo,Santos,01:hmac:CHF4eIrtTNgAooU9v4h9Qjc+txBnMidQTjdjWuaDTTA=,01:enc:KZ5n5GtaXACco65AXk48BQO2durDNR2ULc4YxmMC8NaZZKKJiksU1IwFadAvV4iBQ1Bus5TU5c4biez3bilfTY8=
Mateo,Jackson,01:hmac:iIRnjfNBzryusIJ1w35lgNzeY1RQ1bSfq6PDHW8Xrbk=,01:enc:mLKpS5HIOSgphdEsrzhEdIp/eN9nBO2gAbIygt4OFn4LalYn9Xyj/XUWXlmn8zFe2T4kyDTD8kGOvpQEUGxAUFk=
Diego,Ramirez,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:rmZhT98Zm+IIGw1UTjMIJP4IrW/AAltBLMXcHvnYfRgmWP623VFQ6aUnhsb2MDqEw4G5Uwg5rKKZepUxx5uKbfk=
Jorge,Souza,01:hmac:3BxJdXiFFyZ8HBbYNqqEhBVqhNOd7s2ZiKUe7QiTyo8=,01:enc:vVaqWC1VRbhvkf8gnuR7q0zxVPcvEjuaglYz34+KyyLcGZLpAmsDUc6wZ07f2KvHoOySqRsEU7dG1QfdHYcTSWE=
Terry,Whitlock01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:3c9VEWbODO/xbQjdGuccLvI7oZTBdPU+SyrJIyr2kudfAxbuMQ2uRdU/q7rbgyJjxZS8M2U35ILJf/lDgTyg7cM=
Jane,Doe,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:9RWv46YLveykeNZ/G0NdlYFg+AVdOnu05hHyAYTQkPLHnyX+0/jbzD/g9ZT8GCgVE9aB5bV4ooJIXHGBVMXcjrQ=

位置資料表資料架構

位置資料架構具有以下造型。

{
  "headerRow": false,
  "columns": [
    [
      {
        "targetHeader": STRING,
        "type": TYPE,
        "pad": PAD
      },
      {
        "targetHeader": STRING,
        "type": TYPE,
        "pad": PAD
      }
    ],
    [],
    ...
  ]
}

如果headerRow是false，則物件中的下一個欄位是columns，其中包含一組項目。每個項目本身就是零個或多個位置資料行結構描述 (無sourceHeader欄位) 的陣列，這些結構描述輸出應包含的JSON物件。

  • sourceHeader— 資料衍生自之來源資料行的STRING標頭名稱。

    注意

    在位置結構描述中必須省略此欄位。在位置結構描述中，來源資料行是由結構描述檔案中資料行對應的索引推斷出來的。

  • targetHeader— 輸出檔案中對應欄的STRING標頭名稱。

    注意

    位置資料架構需要此欄位。

  • type— 輸TYPE出檔案中目標欄的。也就是說，其中之一 cleartextsealed，或fingerprint取決於在協同作業中使用欄的方式。

  • pad— 資料行結構描述物件的欄位，只有在是時才會TYPE出現sealed。的對應值PAD是描述資料在加密之前應如何填充資料的物件。

    {
  "type": PAD_TYPE,
  "length": INT
}

    要指定預加密填充，type並length使用如下：

    • PAD_TYPEas none-不填充將應用於列的數據，並且該length字段不適用（也就是省略）。

    • PAD_TYPEas fixed — 資料行的資料會填補至指定length的位元組。

    • PAD_TYPEas max — 資料行的資料會填補至最長值的位元組長度加上一個額外length位元組的大小。

      注意

      fixed如果您提前知道列數據的字節大小的上限，則非常有用。如果該資料行中的任何資料超過指定的資料，就會引發錯誤length。

      max當輸入數據的確切大小未知時很方便，因為無論數據大小如何，它都可以工作。不過，max需要額外的處理時間，因為它會加密資料兩次。 max在讀入暫存檔案時加密資料一次，並在已知資料行中最長的資料項目之後加密一次。

      此外，最長值的長度不會在客戶端的調用之間保存。如果您計劃批次加密資料，或定期加密新資料，請注意產生的密碼文字長度可能會因批次而異。

以下是位置資料架構的範例。

{
  "headerRow": false,
  "columns": [
    [
      {
        "targetHeader": "name",
        "type": "cleartext"
      }
    ],
    [
      {
        "targetHeader": "city_sealed",
        "type": "sealed",
        "pad": {
          "type": "max",
          "length": 16
        }
      }
    ],
    [
      {
        "targetHeader": "phone_number_fingerprint",
        "type": "fingerprint"
      },
      {
        "targetHeader": "phone_number_sealed",
        "type": "sealed",
        "pad": {
          "type": "fixed",
          "length": 20
        }
      }
    ]
  ]
}

作為一個複雜的例子，如果 .csv 文件沒有帶標題的第一行，則以下是一個示例。

Jorge,Souza,12345 Mills Rd,Anytown,SC, 703 -555 -1234,CEO, 10,
Paulo,Santos, 0 Street,Anytown,MD, 404-555-111,CIO, 9,This is a really long note that could really be a paragraph
Mateo,Jackson, 1 Two St,Anytown,NY, 304-555-1324,COO, 9, ""
Terry,Whitlock, 4 N St,Anytown,VA, 407-555-8888,EA, 7,Secret notes
Diego,Ramirez, 9 Hollows Rd,Anytown,VA, 407-555-1222,SDE I, 4,null
John,Doe, 8 Hollows Rd,Anytown,VA, 407-555-4321,SDE I, 4,Jane's younger brother
Jane,Doe, 8 Hollows Rd,Anytown,VA, 407-555-4322,SDE II, 5,John's older sister

位置結構描述具有以下形式。

{
  "headerRow": false,
  "columns": [
    [
      {
        "targetHeader": "GivenName",
        "type": "cleartext"
      }
    ],
    [
      {
        "targetHeader": "Surname",
        "type": "cleartext"
      }
    ],
    [],
    [],
    [
      {
        "targetHeader": "State_Join",
        "type": "fingerprint"
      },
      {
        "targetHeader": "State",
        "type": "sealed",
        "pad": {
          "type": "none"
        }
      }
    ],
    [],
    [],
    [],
    []
  ]
}

上述結構描述會產生下列輸出檔案，其中包含指定目標標頭的標頭資料列。

givenname,surname,state_fingerprint,state
Mateo,Jackson,01:hmac:iIRnjfNBzryusIJ1w35lgNzeY1RQ1bSfq6PDHW8Xrbk=,01:enc:ENS6QD3cMVl9vQEGfe9MNWfR0UOupchswZFr94zOMG5jY/Q8m/Y5SA89dJwKpT5rGPp8e36h6klwDoslpFzGvU0=
Jorge,Souza,01:hmac:3BxJdXiFFyZ8HBbYNqqEhBVqhNOd7s2ZiKUe7QiTyo8=,01:enc:LKo0zirq2++XEIIIMNRjAsGMdyWUDwYaum0B+IFP+rUf1BNeZDJjtFe1Z+zbZfXQWwJy52Rt7HqvAb2WIK1oMmk=
Paulo,Santos,01:hmac:CHF4eIrtTNgAooU9v4h9Qjc+txBnMidQTjdjWuaDTTA=,01:enc:MyQKyWxJ9kvK1xDQQtXlUNwv3F+yrBRr0xrUY/1BGg5KFgOn9pK+MZ7g+ZNqZEPcPz4lht1u0t/wbTaqzOCLXFQ=
Jane,Doe,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:Pd8sbITBfb0/ttUB4svVsgoYkDfnDvgkvxzeci0Yxq54rLSwccy1o3/B50C3cpkkn56dovCwzgmmPNwrmCmYtb4=
Terry,Whitlock01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:Qmtzu3B3GAXKh2KkRYTiEAaMopYedsSdF2e/ADUiBQ9kv2CxKPzWyYTD3ztmKPMka19dHre5VhUHNpO3O+j1AQ8=
Diego,Ramirez,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:ysdg+GHKdeZrS/geBIooOEPLHG68MsWpx1dh3xjb+fG5rmFmqUcJLNuuYBHhHAlxchM2WVeV1fmHkBX3mvZNvkc=
John,Doe,01:hmac:UK8s8Cn/WR2JO/To2dTxWD73aDEe2ZUXeSHy3Tv+1Mk=,01:enc:9uX0wZuO7kAPAx+Hf6uvQownkWqFSKtWS7gQIJSe5aXFquKWCK6yZN0X5Ea2N3bn03Uj1kh0agDWoiP9FRZGJA4=