リテンションポリシーを更新

cURL

curl -i -X PUT "https://api.box.com/2.0/retention_policies/982312" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "disposition_action": "permanently_delete"
     }'

await client.retentionPolicies.updateRetentionPolicyById(retentionPolicy.id, {
  requestBody: {
    policyName: updatedRetentionPolicyName,
  } satisfies UpdateRetentionPolicyByIdRequestBody,
} satisfies UpdateRetentionPolicyByIdOptionalsInput);

await client.RetentionPolicies.UpdateRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id, requestBody: new UpdateRetentionPolicyByIdRequestBody() { PolicyName = updatedRetentionPolicyName });

{
  "id": "12345",
  "type": "retention_policy",
  "policy_name": "Some Policy Name",
  "retention_length": "365",
  "disposition_action": "permanently_delete",
  "max_extension_length": "365",
  "description": "Policy to retain all reports for at least one month",
  "policy_type": "finite",
  "retention_type": "non_modifiable",
  "status": "active",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "can_owner_extend_retention": false,
  "are_owners_notified": false,
  "custom_notification_recipients": [
    {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    }
  ],
  "assignment_counts": {
    "enterprise": 1,
    "folder": 1,
    "metadata_template": 1
  }
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

PUT

retention_policies

{retention_policy_id}

cURL

curl -i -X PUT "https://api.box.com/2.0/retention_policies/982312" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "disposition_action": "permanently_delete"
     }'

await client.retentionPolicies.updateRetentionPolicyById(retentionPolicy.id, {
  requestBody: {
    policyName: updatedRetentionPolicyName,
  } satisfies UpdateRetentionPolicyByIdRequestBody,
} satisfies UpdateRetentionPolicyByIdOptionalsInput);

await client.RetentionPolicies.UpdateRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id, requestBody: new UpdateRetentionPolicyByIdRequestBody() { PolicyName = updatedRetentionPolicyName });

{
  "id": "12345",
  "type": "retention_policy",
  "policy_name": "Some Policy Name",
  "retention_length": "365",
  "disposition_action": "permanently_delete",
  "max_extension_length": "365",
  "description": "Policy to retain all reports for at least one month",
  "policy_type": "finite",
  "retention_type": "non_modifiable",
  "status": "active",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "can_owner_extend_retention": false,
  "are_owners_notified": false,
  "custom_notification_recipients": [
    {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    }
  ],
  "assignment_counts": {
    "enterprise": 1,
    "folder": 1,
    "metadata_template": 1
  }
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

このリソースは、バージョン2024.0のエンドポイントで使用されています。詳細については、 Box APIのバージョン管理を参照してください。「Box SDKのバージョニング戦略について詳しく学ぶ。」

承認

Authorization

string

header

必須

The access token received from the authorization server in the OAuth 2.0 flow.

パスパラメータ

retention_policy_id

string

必須

リテンションポリシーのID。

ボディ

application/json

policy_name

string | null

リテンションポリシーの名前。

例:

"Some Policy Name"

description

string | null

リテンションポリシーのテキストによる追加の説明。

例:

"Policy to retain all reports for at least one month"

disposition_action

リテンションポリシーの廃棄アクション。このアクションをpermanently_deleteに設定すると、ポリシーによって保持されているコンテンツが完全に削除されます。remove_retentionに設定すると、コンテンツへのリテンションポリシーの適用が解除され、リテンションポリシーの有効期限が切れた後は、ユーザーがコンテンツを削除できるようになります。disposition_actionを変更しない場合はnullを使用できます。

利用可能なオプション:

permanently_delete,

remove_retention

例:

"permanently_delete"

retention_type

string | null

以下のリテンションの種類を指定します。

modifiable: リテンションポリシーを変更できます。たとえば、フォルダの追加と削除、ポリシー期間の短縮と延長、または割り当ての削除を行うことができます。リテンションポリシーが規制目的に関連していない場合はこの種類を使用してください。
non-modifiable: フォルダの追加、期間の延長、ポリシーの撤回、廃棄アクションまたは通知設定の変更という限られた方法でしかリテンションポリシーを変更できません。割り当ての削除やポリシー期間の短縮など、その他の操作は実行できません。規制に関するリテンションポリシーを確実に遵守する場合はこの種類を使用してください。

リテンションポリシーを更新する際は、non-modifiableの種類のみを使用できます。modifiableポリシーをnon-modifiableに変換することはできますが、その逆はできません。

例:

"non-modifiable"

retention_length

リテンションポリシーの期間。この値はリテンションポリシーがコンテンツに割り当てられた後、有効である日数を示します。ポリシーのpolicy_typeがindefiniteである場合は、retention_lengthもindefiniteになります。

例:

"365"

status

string | null

リテンションポリシーを撤回する場合に使用します。

ポリシーを撤回しない場合は、このパラメータを含めないようにするか、このパラメータをnullに設定します。

例:

"retired"

can_owner_extend_retention

boolean | null

元のリテンション期間が終了に近づいたときに、ポリシーが適用されている項目の所有者がリテンションを延長できるかどうかを決定します。

例:

false

max_extension_length

リテンション期間を延長できる上限。この値は、ポリシーが適用されているファイルのリテンション期間を延長できる日数を指定します。ポリシーのタイプが「finite」で廃棄アクションが「permanently_delete」の場合にのみ指定でき、それ以外の場合、サーバーはステータス400を返します。この値が「none」である場合、リテンションは延長できません。

利用可能なオプション:

none

例:

"365"

are_owners_notified

boolean | null

リテンション期間が終了に近づいたときに、ポリシーが適用されている項目の所有者と共同所有者に通知するかどうかを決定します。

例:

false

custom_notification_recipients

ユーザー (Base) · object[] | null

リテンション期間が終了に近づいたときに通知されるユーザーのリスト。

Show child attributes

レスポンス

更新されたリテンションポリシーオブジェクトを返します。

リテンションポリシーは、指定した期間にわたってコンテンツが完全に削除されるのを防止します。管理者はリテンションポリシーを作成して特定のフォルダ、メタデータテンプレート、または企業全体に割り当てることができます。この機能を使用するには、アプリケーション管理コンソールから、APIキーに対して [リテンションポリシーを管理する] スコープを有効にする必要があります。

string

必須

リテンションポリシーを表す一意の識別子。

例:

"12345"

type

enum<string>

必須

値は常にretention_policyになります。

利用可能なオプション:

retention_policy

例:

"retention_policy"

policy_name

string

リテンションポリシーの名前。

例:

"Some Policy Name"

retention_length

string<int32>

例:

"365"

disposition_action

enum<string>

利用可能なオプション:

permanently_delete,

remove_retention

例:

"permanently_delete"

max_extension_length

リテンション期間を延長できる上限。この値は、ポリシーが適用されているファイルのリテンション期間を延長できる日数を指定します。ポリシーのタイプが「finite」以外、廃棄アクションが「permanently_delete」以外、または延長期間の上限が定義されていない場合、このフィールドは「none」に設定されます。

利用可能なオプション:

none

例:

"365"

description

string

リテンションポリシーのテキストによる追加の説明。

例:

"Policy to retain all reports for at least one month"

policy_type

enum<string>

リテンションポリシーのタイプ。リテンションポリシーのタイプは、finite (コンテンツを保持する期間が事前にわかっている場合)、またはindefinite (コンテンツを保持する期間が不明な場合) のいずれかになります。

利用可能なオプション:

finite,

indefinite

例:

"finite"

retention_type

enum<string>

以下のリテンションの種類を指定します。

modifiable: リテンションポリシーを変更できます。たとえば、フォルダの追加と削除、ポリシー期間の短縮と延長、または割り当ての削除を行うことができます。リテンションポリシーが規制目的に関連していない場合はこの種類を使用してください。
non-modifiable: フォルダの追加、期間の延長、ポリシーの撤回、廃棄アクションまたは通知設定の変更という限られた方法でしかリテンションポリシーを変更できません。割り当ての削除やポリシー期間の短縮など、その他の操作は実行できません。規制に関するリテンションポリシーを確実に遵守する場合はこの種類を使用してください。

利用可能なオプション:

modifiable,

non_modifiable

例:

"non_modifiable"

status

enum<string>

リテンションポリシーのステータス。ポリシーのステータスは、管理者が明示的に撤回しない限り、activeになります (撤回されたポリシーのステータスはretiredになります)。一度廃止したポリシーを再度アクティブにすることはできません。

利用可能なオプション:

active,

retired

例:

"active"

created_by

ユーザー (Mini) · object

リテンションポリシーを作成したユーザーをMini版のユーザーオブジェクトで表示。

Show child attributes

created_at

string<date-time>

リテンションポリシーオブジェクトが作成された日時。

例:

"2012-12-12T10:53:43-08:00"

modified_at

string<date-time>

リテンションポリシーオブジェクトが最後に変更された日時。

例:

"2012-12-12T10:53:43-08:00"

can_owner_extend_retention

boolean

元のリテンション期間が終了に近づいたときに、ポリシーが適用されている項目の所有者がリテンションを延長できるかどうかを決定します。

例:

false

are_owners_notified

boolean

リテンション期間が終了に近づいたときに、ポリシーが適用されている項目の所有者と共同所有者に通知するかどうかを決定します。

例:

false

custom_notification_recipients

ユーザー (Mini) · object[]

リテンションポリシーの期間が終了に近づいたときに通知されるユーザーのリスト。

Show child attributes

assignment_counts

object

項目タイプごとに、リテンションポリシーによる割り当て数をカウントします。

Show child attributes

最終更新日 2026年1月23日

APIリファレンス

APIリファレンス

APIリファレンス

リテンションポリシーを更新

承認

パスパラメータ

ボディ

レスポンス