グループの作成

ログイン済みのユーザーはグループを作成できます。グループを作成したユーザーが、このグループのオーナーとなります。

グループを作成する際は、以下の組み合わせを選択できます。

グループ ID を Kii Cloud が自動発行するか、クライアントから指定するか
グループ作成時にメンバーを同時に指定するか、しないか

ここでは、以下の 3 通りの方法でグループを作成するサンプルコードを示します。サンプルコードのパラメーターにより、上記の組み合わせを実現できます。

ID の自動発行によるグループの作成
メンバー指定でのグループの作成
ID 指定でのグループの作成

ID の自動発行によるグループの作成

以下にグループ作成の例を挙げます。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.GroupCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups" \
  -d '{
        "name" : "testing group",
        "owner" : "{USER_ID}"
      }'

グループ名を "name" に指定します。グループ名は 190 文字までで、使用できる文字などの制限は特にありません。既存のグループ名との重複も可能です。

グループのオーナーとなるユーザーの ID を "owner" に指定します。

グループの作成に成功すると、Kii Cloud はグループ ID を 201 応答として返します。

< 201
< Location: https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}
< Content-Type: application/vnd.kii.GroupCreationResponse+json
<{
  "groupID" : "{GROUP_ID}",
  "notFoundUsers" : []
}

グループ作成処理時に指定したオーナーが Kii Cloud 上に存在しなかった場合は、グループ作成は失敗し、404 応答（USER_NOT_FOUND）が返されます。

グループ ID は後ほどグループを参照する際に使用します。作成時に指定したグループ名では、作成済みのグループを参照できません。

メンバー指定でのグループの作成

グループ作成と同時に、グループメンバーを追加できます。以下に例を挙げます。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.GroupCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups" \
  -d '{
        "name" : "testing group",
        "owner" : "{USER_ID}",
        "members" : [
          "{USER_ID_OF_MEMBER_1}",
          "{USER_ID_OF_MEMBER_2}"
        ]
      }'

追加するグループメンバーのユーザー ID を "members" に指定します。

グループの作成およびグループメンバーの追加に成功すると、Kii Cloud は最初の例と同様にグループ ID を 201 応答として返します。

グループメンバーとして指定したユーザーの一部（または全員）が Kii Cloud 上に存在しなかった場合、グループ作成自体は成功します。この場合、レスポンスにおいて存在しなかったユーザーのリストが次のように返されます。

< 201
< Location: https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}
< Content-Type: application/vnd.kii.GroupCreationResponse+json
<
{
  "groupID" : "{GROUP_ID}",
  "notFoundUsers" : [ "{NON_EXISTING_USER_ID_1}", ... ]
}

なお、グループメンバーは後ほど追加することもできます。

ID 指定でのグループの作成

先ほどまでの例ではグループ ID が自動的に付与されますが、グループ作成時にグループ ID を明示的に指定することもできます。

グループ ID を指定してグループを作成する例を以下に挙げます。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.GroupCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}" \
  -d '{
        "name" : "testing group",
        "owner" : "{USER_ID}"
      }'

利用したいグループ ID を {GROUP_ID} に指定してください。グループ ID は、小文字の英数字、"."、"-"、"_" から構成される 30 文字までの文字列として指定します。既存のグループ ID と重複した場合はエラーになります。

グループの作成に成功すると、Kii Cloud は最初の例と同様に 201 応答を返します。