はじめに:Googleデータポータルの公式ドキュメント誤り多し
Googleデータポータル(旧Googleデータスタジオ)はREST APIを持っています。
パーミッション制御ぐらいしかできないうえ、Google Workspace/Cloud Identityが必要になるのでユーザーはとても限定的で、利用者の絶対数が少ないせいか公式のドキュメントの記述がいい加減です。
少し苦労したのでエラッタ(誤記訂正表)をのっけます。
GoogleデータポータルAPI公式ドキュメントのエラッタ
概要
- 2021/09/15時点の情報になります
- 基本的に英語版をベースとしますが、日本語版には英語版にはない誤記がある ため可能な限りそれらもキャッチアップします
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
ソース
脱落:足りない要素がある
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
ソース
誤記:要素 permissions
以下の構造が誤っている
Permissions
型の子要素 permissions
(ややこしい)以下の構造が誤っています。
{
"permissions": {[Role]: Member[]},
"etag": string
}
ではなく、正しくは
{
"permissions": {
[Role]: {
"members": Member[]
}
},
"etag": string
}
です。具体例としては
{
"permissions": {
"OWNER": {
"members": ["user:owner@example.com"]
},
"VIEWER": {
"members": ["viewer:user@example.com"]
}
},
"etag": "abcdefgh"
}
です。
余談ですが、 etag
は省略可能要素です。
通常、リクエスト時は省略して使います。レスポンス時にAPIが値をつけて返してきます(後述)。
Permissions
Get
ソース
誤記:role
パラメーターはない
Parametersに role
の記述がありますが、URIを見てわかるとおり、実際には role
を指定することはありません。
Patch
ソース
曖昧:リクエストボディの permissions.etag
は不要
誤記というほどではないかもしれないです(他のAPIドキュメントでも同じレベルの書き方をしているものはあるので)。
Request bodyに permissions
プロパティがあります。
permissions
プロパティは Permission
型なので子要素として etag
要素があるのですが、これはリクエストボディの場合には書かなくていいです。
具体例は後述の「おまけ」を参照してください。
なお、レスポンスとして返ってくる Permission
型オブジェクトにはetagが付与されています。
[日本語版のみ] assetId
ではなく name
リクエスト本文に assetId
というプロパティがありますが、正しくは name
です。なお、指定する値の記述は正しく、アセットのIDを指定します。
Add Members
ソース
誤記:PATCHではなくPOST
HTTP requestにPATCHと書いてありますが、POSTの誤りです。
[日本語版のみ] 誤記:assetId
ではなく name
リクエスト本文に assetId
というプロパティがありますが、正しくは name
です。なお、指定する値の記述は正しく、アセットのIDを指定します。
Revoke All Permissions
ソース
[日本語版のみ] 誤記:assetId
ではなく name
リクエスト本文に assetId
というプロパティがありますが、正しくは name
です。なお、指定する値の記述は正しく、アセットのIDを指定します。
おわりに
時間ができたらissue trackerに投げておきます。
おまけ:リクエスト例
PATCH v1/assets/{asset_id}/permissions
の例です。
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"]
}
}
}
}'