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

# （選用） 建立結構描述 （進階使用者）
<a name="create-schema"></a>

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

以下是具有或沒有資料欄標頭之輸入檔案的 JSON 結構描述檔案格式說明。進階使用者可以視需要直接寫入或修改結構描述。

**注意**  
C3R 加密用戶端可以透過 中所述的互動式程序[範例：使用 sealed、 fingerprint和 cleartext資料欄產生加密結構描述](gen-encryption-schema-csv.md#gen-encryption-schema)或透過建立 stub 範本來協助您建立結構描述。

## 映射和位置資料表結構描述
<a name="mapped-and-positional-schemas"></a>

下節說明兩種資料表結構描述：
+ **映射的資料表結構描述** – 此結構描述用於加密具有標頭列和檔案的 .csv Apache Parquet 檔案。
+ **位置資料表結構描述** – 此結構描述用於加密沒有標頭列的 .csv 檔案。

C3R 加密用戶端可以加密協作的表格式檔案。若要這樣做，它必須具有對應的結構描述檔案，指定應如何從輸入衍生加密的輸出。

C3R 加密用戶端可以透過在命令列執行 C3R 加密用戶端結構描述命令，協助產生 `INPUT` 檔案的結構描述。命令的範例為 `java -jar c3r-cli.jar schema --interactive INPUT`。

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

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

1. 要保留的目標欄 cleartext

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

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

此資訊在資料表特定的 JSON 結構描述檔案中編碼，其中包含單一物件，其`headerRow`欄位為布林值。值必須是`true`具有標頭列Parquet的檔案和 .csv 檔案，`false`否則為 。

### 映射的資料表結構描述
<a name="mapped-schemas"></a>

映射的結構描述具有下列形狀。

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

如果 `headerRow`為 `true`，則物件中的下一個欄位為 `columns`，其中包含將來源標頭映射至目標標頭的欄結構描述陣列 （即描述輸出欄應包含內容的 JSON 物件）。
+ `sourceHeader` – 資料衍生來源欄的`STRING`標頭名稱。
**注意**  
相同的來源資料欄可用於多個目標資料欄。  
來自輸入檔案的資料欄未列在結構描述的任何`sourceHeader`位置，不會出現在輸出檔案中。
+ `targetHeader` – 輸出檔案中對應欄的`STRING`標頭名稱。
**注意**  
對於映射的結構描述，此欄位是選用的。如果省略此欄位，`sourceHeader`則會針對輸出中的標頭名稱重複使用 。如果輸出資料欄分別是fingerprint資料欄或sealed資料欄，`_sealed`則會附加 `_fingerprint` 或 。
+ `type` – 輸出檔案中目標欄`TYPE`的 。也就是說， `cleartext`、 `sealed`或 之一，`fingerprint`取決於資料欄在協同合作中的使用方式。
+ `pad` – 資料欄結構描述物件的欄位，只有在 `TYPE`為 時才存在`sealed`。其對應值`PAD`為 物件，描述資料在加密之前應如何填入。

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

  若要指定預先加密填補， `type` `length` 使用方式如下：
  + `PAD_TYPE` as `none` – 不會將填補套用至資料欄的資料，且 `length` 欄位不適用 （即省略）。
  + `PAD_TYPE` as `fixed` – 資料欄的資料會填入指定的`length`位元組。
  + `PAD_TYPE` as `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
```

在下列映射結構描述範例中，資料欄 `FirstName`和 `LastName`是資料`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=
```

### 位置資料表結構描述
<a name="positional-schemas"></a>

位置結構描述的形狀如下。

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

如果 `headerRow`為 `false`，則物件中的下一個欄位為 `columns`，其中包含項目陣列。每個項目本身都是零個或多個位置資料欄結構描述 （無`sourceHeader`欄位） 的陣列，這些結構描述輸出應包含的內容。
+ `sourceHeader` – 資料衍生來源欄的`STRING`標頭名稱。
**注意**  
必須在位置結構描述中省略此欄位。在位置結構描述中，來源資料欄由結構描述檔案中資料欄的對應索引推斷。
+ `targetHeader` – 輸出檔案中對應欄的`STRING`標頭名稱。
**注意**  
位置結構描述需要此欄位。
+ `type` – 輸出檔案中目標欄`TYPE`的 。也就是說， `cleartext`、 `sealed`或 之一，`fingerprint`取決於資料欄在協同合作中的使用方式。
+ `pad` – 資料欄結構描述物件的欄位，只有在 `TYPE`為 時才存在`sealed`。其對應值`PAD`為 物件，描述資料在加密之前應如何填入。

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

  若要指定預先加密填補， `type` `length` 使用方式如下：
  + `PAD_TYPE` as `none` – 不會將填補套用至資料欄的資料，且 `length` 欄位不適用 （即省略）。
  + `PAD_TYPE` as `fixed` – 資料欄的資料會填入指定的`length`位元組。
  + `PAD_TYPE` as `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=
```