# Audience APIを使用したアトリビュートグルーピングの作成

アトリビュートグルーピングは、Treasure Dataのペアレントセグメントオブジェクトに含まれる`attributes`オブジェクトの`groupingName`フィールドの値によって定義されます。デフォルトでは、`groupingName`はNULLに設定されています。ただし、`groupingName`が文字列値に設定されている場合、その名前でTreasure コンソールにアトリビュートグルーピングが作成されます。`groupingName`にその文字列が指定されている`attributes`オブジェクトは、すべてアトリビュートグルーピングに含まれます。

この記事の最後にある図1には、ペアレントセグメントオブジェクトの完全なリストがあります。オブジェクトの`attributes`(つまり、セグメントのテーブルカラム)は34行目から始まります。`attributes`オブジェクトで記述されている両方のオブジェクトの`groupingName`が`null`に設定されていることに注意してください(47行目と61行目)。


```
    34:   "attributes":[
    35:      {
    36:         "audienceId":"12345",
    37:         "id":"56662",
    38:         "name":"c1-test",
    39:         "type":"string",
    40:         "parentDatabaseName":"_mobile_sdk",
    41:         "parentTableName":"android",
    42:         "parentColumn":"c1",
    43:         "parentKey":"c0",
    44:         "foreignKey":"c_comment",
    45:         "matrixColumnName":"c1",
    46:         "usedBySegmentInsight":false,
    47:         "groupingName": null
    48:      },
    49:      {
    50:         "audienceId":"12345",
    51:         "id":"56663",
    52:         "name":"c2-test",
    53:         "type":"string",
    54:         "parentDatabaseName":"_mobile_sdk",
    55:         "parentTableName":"android",
    56:         "parentColumn":"activity_date",
    57:         "parentKey":"c0",
    58:         "foreignKey":"c_comment",
    59:         "matrixColumnName":"activity_date",
    60:         "usedBySegmentInsight":false,
    61:         "groupingName": null
    62:      }
```

ただし、`groupingName`が例えば`wtt_test`に変更された場合(47行目に示されているように)、`wtt_test`という名前のアトリビュートグルーピングが作成されます。


```
    35:      {
    36:         "audienceId":"12345",
    37:         "id":"56662",
    38:         "name":"c1-test",
    39:         "type":"string",
    40:         "parentDatabaseName":"_mobile_sdk",
    41:         "parentTableName":"android",
    42:         "parentColumn":"c1",
    43:         "parentKey":"c0",
    44:         "foreignKey":"c_comment",
    45:         "matrixColumnName":"c1",
    46:         "usedBySegmentInsight":false,
    47:         "groupingName": 'wtt_test'
    48:      },
```

![](/assets/attrgrpconsole.8ba1bace301a487115dfa39b431161fb6283d15b6c5ddba5e12cd23cc259e326.cf3845cb.png)

# アトリビュートグルーピングの作成

アトリビュートグルーピングを作成するには、3つのステップがあります:

1. ペアレントセグメントIDの取得
2. ペアレントセグメントオブジェクトの取得
3. `groupingName`を使用したペアレントセグメントオブジェクトのパッチ


## ペアレントセグメントIDの取得

作業対象のペアレントセグメントのIDを取得する方法は2つあります。Treasure コンソールを使用する方法と、Audience APIコールを行う方法です。

Treasure コンソールで、Audience Studioに移動し、作業対象のペアレントセグメントを選択します。セグメントIDは、URLの`/app/ps/`というテキストの後に記載されています。

![](/assets/consoleps.9dfc3a18810682c0a90f219583260a7d0f491393f806376ee59f821b4ae3f2a3.cf3845cb.png)

または、すべてのペアレントセグメントを表示するためのAudience APIコールを行うと、すべてのペアレントセグメントの`id`と`name`がレスポンスの一部として返されます。例えば、以下に示すようなコールを実行できます。レスポンスはフォーマットされていないJSONで返されます。ただし、この例では、レスポンスが編集され、読みやすくフォーマットされています。


```bash
$ curl -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' 'https://api-cdp.treasuredata.com/audiences/'
```


```json
{
   "id":"12345",
   "name":"Attribute Grouping",
   "description":"Contains grouping names set through Audience API.",
   "scheduleType":"none",
   "scheduleOption":null,
    .
    .
    .
}
```

レスポンスに多数のペアレントセグメントがある場合、出力を簡素化する1つの戦略は、フォーマットしてからidと`name`でフィルタリングすることです。これを実現する方法の例を以下に示します。


```bash
curl -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' 'https://api-cdp.treasuredata.com/audiences/' | python -m json.tool | grep '^\s\s\s\s\s\s\s\s\"id\|^\s\s\s\s\s\s\s\s\"name'
```


```bash
% Total    % Received % Xferd  Average Speed   Time    Time     Time  CurrentDload  Upload   Total   Spent    Left  Speed
100 1188k    0 1188k    0     0  81378      0 --:--:--  0:00:14 --:--:--  323k
"id": "12345",
"name": "Attribute Grouping",
"id": "23456",
"name": "PS1",
"id": "34567",
"name": "PS2",
"id": "45678",
"name": "Test Segment",
    .
    .
    .
```

## ペアレントセグメントオブジェクトの取得

ペアレントセグメントIDを取得したら、ペアレントセグメントオブジェクトを取得できます。以下の例では、ペアレントセグメントオブジェクトIDは`12345`です。


```bash
curl -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' https://api-cdp.treasuredata.com/audiences/12345
```

レスポンスはフォーマットされていないJSONとして返されます。JSONフォーマットツールを使用してレスポンスを読みやすくすることが役立ちます。例えば、Pythonの`json.tool`を使用してレスポンスをフォーマットする例を以下に示します。


```bash
$ curl -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' 'https://api-cdp.treasuredata.com/audiences/12345' | python -m json.tool
```

`groupingName`を使用したペアレントセグメントオブジェクトのパッチ

ペアレントセグメントオブジェクトを取得したら、レスポンスを編集し、グルーピングに含めたい1つ以上のアトリビュートの`groupingName`の`null`設定を変更できます。`groupingName`に指定する文字列値が、アトリビュートグルーピングの名前になります。

ペアレントセグメントオブジェクトの編集が完了したら、この編集されたオブジェクトをPATCHリクエストのリクエストペイロードとして使用します。

複数の埋め込みオブジェクトを含む大きなフォーマットされていないJSONオブジェクトは、扱いにくい場合があります。そのため、リクエストペイロードとして使用されるペアレントセグメントオブジェクトはフォーマットされ、`attrGroupingRequest.json`という名前のファイルに保存されています(以下の図1を参照)。ファイルを必要に応じて編集した後、次のようなPATCHリクエストにファイルを含めることができます:


```bash
$ curl --location --request PATCH -H 'AUTHORIZATION: TD1 1/1234567891234567891234567891234567891234' -H 'Content-Type: application/json' -d @attrGroupingRequest.json https://api-cdp.treasuredata.com/audiences/12345
```

# アトリビュートグルーピングの変更

アトリビュートグルーピングの変更は、ペアレントセグメントオブジェクトを編集し、必要に応じて`groupingName`の値を変更することで構成されます。すべてのアトリビュートグルーピングからカラムを削除するには`null`に変更するか、名前を別のアトリビュートグルーピングに変更して、事実上カラムを新しいアトリビュートグルーピングに移動できます。ペアレントセグメントオブジェクトを変更した後、変更されたオブジェクトを使用してPATCHリクエストを送信します。

# アトリビュートグルーピングの削除

アトリビュートグルーピングを削除するには、ペアレントセグメントオブジェクトを編集し、削除したいアトリビュートグルーピングの名前を削除します。`groupingName`のすべてのインスタンスから名前を削除します。ほとんどの場合、値を単に`null`に変更します。ペアレントセグメントオブジェクトを変更した後、新しいオブジェクトを使用してPATCHリクエストを送信します。

図1: ペアレントセグメントオブジェクトを含むattrGroupingRequest.jsonのファイルリスト


```json
{
  "id": "12345",
  "name": "Attribute Grouping",
  "description": "Contains grouping names set through Audience API.",
  "scheduleType": "none",
  "scheduleOption": null,
  "timezone": "UTC",
  "createdAt": "2022-02-10T19:17:45.107Z",
  "updatedAt": "2022-02-10T19:17:45.107Z",
  "createdBy": {
    "id": "111",
    "td_user_id": "4567",
    "name": "firstName lastName"
  },
  "updatedBy": {
    "id": "3210",
    "td_user_id": "45678",
    "name": "Me"
  },
  "matrixUpdatedAt": "2022-02-10T19:25:09.676Z",
  "workflowHiveOnly": false,
  "hiveEngineVersion": "cdpaudience",
  "hivePoolName": null,
  "prestoPoolName": null,
  "population": 150000,
  "enrichmentWordTaggingEnabled": true,
  "enrichmentIpEnabled": true,
  "enrichmentTdJsSdkEnabled": true,
  "rootFolderId": "987654",
  "master": {
    "parentDatabaseName": "test_db_1",
    "parentTableName": "sample"
  },
  "attributes": [
    {
      "audienceId": "12345",
      "id": "56662",
      "name": "c1-test",
      "type": "string",
      "parentDatabaseName": "_mobile_sdk",
      "parentTableName": "android",
      "parentColumn": "c1",
      "parentKey": "c0",
      "foreignKey": "c_comment",
      "matrixColumnName": "c1",
      "usedBySegmentInsight": false,
      "groupingName": null
    },
    {
      "audienceId": "12345",
      "id": "56663",
      "name": "c2-test",
      "type": "string",
      "parentDatabaseName": "_mobile_sdk",
      "parentTableName": "android",
      "parentColumn": "activity_date",
      "parentKey": "c0",
      "foreignKey": "c_comment",
      "matrixColumnName": "activity_date",
      "usedBySegmentInsight": false,
      "groupingName": null
    }
  ],
  "behaviors": [
    {
      "audienceId": "12345",
      "id": "23456",
      "name": "Orders",
      "parentDatabaseName": "test_db_1",
      "parentTableName": "orders",
      "parentKey": "o_custkey",
      "foreignKey": "c_custkey",
      "matrixDatabaseName": "audience_76543",
      "matrixTableName": "behavior_orders",
      "allColumns": false,
      "scheduleType": "none",
      "scheduleOption": null,
      "defaultTimeFilterEnabled": true,
      "filterRule": {},
      "schema": [
        {
          "name": "o_clerk",
          "type": "string",
          "parentColumn": "o_clerk",
          "matrixColumnName": "o_clerk"
        }
      ]
    }
  ]
}
```