GoogleデータポータルAPI公式ドキュメントのエラッタ（誤記訂正表）

# はじめに：Googleデータポータルの公式ドキュメント誤り多し

Googleデータポータル（旧Googleデータスタジオ）はREST APIを持っています。
パーミッション制御ぐらいしかできないうえ、Google Workspace/Cloud Identityが必要になるのでユーザーはとても限定的で、利用者の絶対数が少ないせいか公式のドキュメントの記述がいい加減です。

少し苦労したのでエラッタ（誤記訂正表）をのっけます。

# GoogleデータポータルAPI公式ドキュメントのエラッタ

## 概要

* 2021/09/15時点の情報になります
* 基本的に英語版をベースとしますが、**日本語版には英語版にはない誤記がある** ため可能な限りそれらもキャッチアップします

## Types

### Roles

#### ソース

https://developers.google.com/datastudio/api/reference/types#Roles

#### 脱落：足りない要素がある

RoleはVIEWER、EDITOR、OWNERのほかにLINK_VIEWER、LINK_EDITORがある。

| Enum Value | Description |
| --- | --- |
| VIEWER | A viewer. |
| EDITOR | An editor. |
| OWNER | An owner. |
| **LINK_VIEWER** | **A viewer which knows this link.** |
| **LINK_EDITOR** | **An editor which knows this link.** |

### Member

#### ソース

https://developers.google.com/datastudio/api/reference/types#Members

#### 脱落：足りない要素がある

user,group,domain,serviceAccountの他にdeletedという要素もある。

* user:
* group:
* domain:
* serviceAccount:
* **deleted:**

deletedは少し特殊な要素で、権限を与えたあとでアカウントが失効するとこの値に置き換わります。

例えば、 `user:foo@example.com` というメンバーに対していずれかの権限を与え、その後 `foo@example.com` アカウントが失効すると、 `deleted:user:foo@example.com?uid=xxx...` のような値に置き換わります。

### Permissions

#### ソース

https://developers.google.com/datastudio/api/reference/types#Permissions

#### 誤記：要素 `permissions` 以下の構造が誤っている

`Permissions` 型の子要素 `permissions` （ややこしい）以下の構造が誤っています。

```json
{
  "permissions": {[Role]: Member[]},
  "etag": string
}
```

ではなく、正しくは

```json
{
  "permissions": {
      [Role]: {
          "members": Member[]
      }
  },
  "etag": string
}
```

です。具体例としては

```json
{
  "permissions": {
      "OWNER": {
          "members": ["user:owner@example.com"]
      },
      "VIEWER": {
          "members": ["viewer:user@example.com"]
      }
  },
  "etag": "abcdefgh"
}
```

です。

余談ですが、 `etag` は省略可能要素です。
通常、リクエスト時は省略して使います。レスポンス時にAPIが値をつけて返してきます（後述）。

## Permissions

### Get

#### ソース

https://developers.google.com/datastudio/api/reference/permissions/get

#### 誤記：`role` パラメーターはない

Parametersに `role` の記述がありますが、URIを見てわかるとおり、実際には `role` を指定することはありません。

### Patch

#### ソース

https://developers.google.com/datastudio/api/reference/permissions/patch

#### 曖昧：リクエストボディの `permissions.etag` は不要

誤記というほどではないかもしれないです（他のAPIドキュメントでも同じレベルの書き方をしているものはあるので）。

Request bodyに `permissions` プロパティがあります。
`permissions` プロパティは `Permission` 型なので子要素として `etag` 要素があるのですが、これはリクエストボディの場合には書かなくていいです。
具体例は後述の「おまけ」を参照してください。

なお、レスポンスとして返ってくる `Permission` 型オブジェクトにはetagが付与されています。

#### [日本語版のみ] `assetId` ではなく `name`

リクエスト本文に `assetId` というプロパティがありますが、正しくは `name` です。なお、指定する値の記述は正しく、アセットのIDを指定します。

### Add Members

#### ソース

https://developers.google.com/datastudio/api/reference/permissions/addMembers

#### 誤記：PATCHではなくPOST

HTTP requestにPATCHと書いてありますが、POSTの誤りです。

#### [日本語版のみ] 誤記：`assetId` ではなく `name`

リクエスト本文に `assetId` というプロパティがありますが、正しくは `name` です。なお、指定する値の記述は正しく、アセットのIDを指定します。

### Revoke All Permissions

#### ソース

https://developers.google.com/datastudio/api/reference/permissions/revokeAllPermissions

#### [日本語版のみ] 誤記：`assetId` ではなく `name`

リクエスト本文に `assetId` というプロパティがありますが、正しくは `name` です。なお、指定する値の記述は正しく、アセットのIDを指定します。

# おわりに

時間ができたらissue trackerに投げておきます。

# おまけ：リクエスト例

`PATCH v1/assets/{asset_id}/permissions` の例です。

```shell
curl --request PATCH 'https://datastudio.googleapis.com/v1/assets/＜アセットID＞/permissions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ＜アクセストークン＞' \
--data-raw '{
    "name": "＜アセットID＞",
    "permissions": {
        "permissions": {
            "OWNER": {
                "members": ["user:owner@example.com"]
            },
            "VIEWER": {
               "members": ["viewer:user@example.com"]
            }
        }
    }
}'
```