Skip to main content

update-allocation 

dci update-allocation <id> [body]

Updates the allocation specified by the Id.

  • id — Allocation ID or name as shown by dci list-allocations. Names resolve (exact, unique substring, or close typo); pass --id to force a literal ID.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Examples​

# Turn on anomaly detection for a single allocation.
dci update-allocation "Team Backyard" anomalyDetection: true
# Rename it and move it to a folder.
dci update-allocation <allocation-id> name: "Team Backyard (prod)", folderId: <folder-id>
# Replace the rule so it matches either of two billing accounts, with the body read from a file.
dci update-allocation <allocation-id> < allocation.json
# allocation.json
{"rule": {"formula": "A",
          "components": [{"key": "billing_account_id", "type": "fixed", "mode": "is",
                          "values": ["012345-ABCDEF-678901", "ABCDEF-012345-678901"]}]}}
# Pull the current allocation, edit it, and push it back as code.
dci update-allocation <allocation-id> < allocation.json
Start from `dci get-allocation <allocation-id> --output json > allocation.json`, edit, then push; the response is the updated allocation.

Request​

Content-Type: application/json

FieldTypeRequiredDescription
namestringAllocation name
descriptionstringAllocation description
anomalyDetectionbooleanWhether anomaly detection is enabled for this allocation. Only applicable to single allocations.
ruleobjectSingle allocation rule. Components can reference other existing allocation rules by using the "allocation_rule" dimension type.
rule.componentsarray of objectyesList of allocation filter components.
rule.components[].keystringyesKey of an existing dimension. Examples: "billing_account_id", "country". When type is "allocation_rule", the key must be set to "allocation_rule". Use GET /analytics/v1/dimensions to retrieve all available dimensions.
rule.components[].typestringyesDimension filter type for allocation rule components. See DimensionsTypes for per-value meanings. Allocation components do not support allocation, attribution, or attribution_group types. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "allocation_rule", "gke", "gke_label".
rule.components[].valuesarray of stringyesValues to filter on. When type is "allocation_rule", the values are IDs of existing allocation rules.
rule.components[].inversebooleanIf true, all selected values will be excluded. Default: false.
rule.components[].includeNullbooleanInclude null values. Default: false.
rule.components[].caseInsensitivebooleanIf true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise. Default: false.
rule.components[].modestringyesFilter mode to apply. When type is "allocation_rule", only "is" and "contains" modes are supported. One of: "is", "starts_with", "ends_with", "contains", "regexp".
rule.formulastringyesFormula for combining components (A is the first component, B is the second one, etc.).
rulesarray of object
rules[].namestringName of the allocation rule.
rules[].descriptionstringDescription of the allocation rule.
rules[].actionstringyesAction to perform with this rule. One of: "create", "update", "select".
rules[].idstringID of existing allocation (required for 'update' or 'select' action).
rules[].componentsarray of objectList of allocation filter components (required for 'create' or 'update' action). Can include components of type "allocation_rule" to reference existing allocation rules.
rules[].components[].keystringyesKey of an existing dimension. Examples: "billing_account_id", "country". When type is "allocation_rule", the key must be set to "allocation_rule". Use GET /analytics/v1/dimensions to retrieve all available dimensions.
rules[].components[].typestringyesDimension filter type for allocation rule components. See DimensionsTypes for per-value meanings. Allocation components do not support allocation, attribution, or attribution_group types. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "allocation_rule", "gke", "gke_label".
rules[].components[].valuesarray of stringyesValues to filter on. When type is "allocation_rule", the values are IDs of existing allocation rules.
rules[].components[].inversebooleanIf true, all selected values will be excluded. Default: false.
rules[].components[].includeNullbooleanInclude null values. Default: false.
rules[].components[].caseInsensitivebooleanIf true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise. Default: false.
rules[].components[].modestringyesFilter mode to apply. When type is "allocation_rule", only "is" and "contains" modes are supported. One of: "is", "starts_with", "ends_with", "contains", "regexp".
rules[].formulastringFormula for combining components (A is the first component, B is the second one, etc.)
unallocatedCostsstringCustom label for values that do not fit into allocation (required for group type allocation).
folderIdstringIdentifier of the folder that contains the allocation. Set to "root" if the allocation is at the top level (not in a folder). Default: "root".
Raw JSON schema
{
  "type": "object",
  "description": "Request body for updating an allocation.",
  "properties": {
    "name": {
      "type": "string",
      "description": "Allocation name",
      "nullable": true
    },
    "description": {
      "type": "string",
      "description": "Allocation description",
      "nullable": true
    },
    "anomalyDetection": {
      "type": "boolean",
      "description": "Whether anomaly detection is enabled for this allocation. Only applicable to single allocations."
    },
    "rule": {
      "required": [
        "components",
        "formula"
      ],
      "type": "object",
      "description": "Single allocation rule. Components can reference other existing allocation rules by using the \"allocation_rule\" dimension type.",
      "nullable": true,
      "properties": {
        "components": {
          "type": "array",
          "description": "List of allocation filter components.",
          "items": {
            "required": [
              "key",
              "type",
              "values",
              "mode"
            ],
            "type": "object",
            "description": "A filter component used inside allocation rules.\nWhen the type is \"allocation_rule\", the component references existing allocation rules (nested allocation rules).\nA maximum nesting depth of 3 levels is supported, and circular references are not allowed.",
            "properties": {
              "key": {
                "type": "string",
                "description": "Key of an existing dimension. Examples: \"billing_account_id\", \"country\". When type is \"allocation_rule\", the key must be set to \"allocation_rule\".\nUse `GET /analytics/v1/dimensions` to retrieve all available dimensions."
              },
              "type": {
                "description": "Dimension filter type for allocation rule components. See `DimensionsTypes` for per-value meanings. Allocation components do not support `allocation`, `attribution`, or `attribution_group` types.",
                "type": "string",
                "enum": [
                  "datetime",
                  "fixed",
                  "optional",
                  "label",
                  "tag",
                  "project_label",
                  "system_label",
                  "allocation_rule",
                  "gke",
                  "gke_label"
                ],
                "x-enumDescriptions": {
                  "fixed": "Standard built-in billing dimensions.",
                  "label": "Customer-defined resource labels; key is the label key.",
                  "tag": "AWS cost allocation tags; key is the tag key.",
                  "project_label": "Google Cloud project-level labels.",
                  "system_label": "DoiT- or provider-generated system labels.",
                  "optional": "Console grouping for label/tag keys; use a concrete subtype in filters.",
                  "datetime": "Time dimensions for date-based filtering.",
                  "allocation_rule": "Reference another allocation rule by ID.",
                  "gke": "Google Kubernetes Engine cost-allocation dimensions.",
                  "gke_label": "GKE workload labels."
                }
              },
              "values": {
                "type": "array",
                "description": "Values to filter on. When type is \"allocation_rule\", the values are IDs of existing allocation rules.",
                "items": {
                  "type": "string"
                }
              },
              "inverse": {
                "type": "boolean",
                "description": "If true, all selected values will be excluded.",
                "default": false
              },
              "includeNull": {
                "type": "boolean",
                "description": "Include null values.",
                "default": false
              },
              "caseInsensitive": {
                "type": "boolean",
                "description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise.",
                "default": false
              },
              "mode": {
                "type": "string",
                "description": "Filter mode to apply. When type is \"allocation_rule\", only \"is\" and \"contains\" modes are supported.",
                "enum": [
                  "is",
                  "starts_with",
                  "ends_with",
                  "contains",
                  "regexp"
                ]
              }
            }
          }
        },
        "formula": {
          "type": "string",
          "description": "Formula for combining components (A is the first component, B is the second one, etc.).",
          "example": "A AND B"
        }
      }
    },
    "rules": {
      "type": "array",
      "items": {
        "required": [
          "action"
        ],
        "type": "object",
        "nullable": true,
        "description": "Allocation rule for a group type allocation. Components can reference other existing allocation rules by using the \"allocation_rule\" dimension type.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the allocation rule."
          },
          "description": {
            "type": "string",
            "description": "Description of the allocation rule."
          },
          "action": {
            "type": "string",
            "description": "Action to perform with this rule.",
            "enum": [
              "create",
              "update",
              "select"
            ]
          },
          "id": {
            "type": "string",
            "description": "ID of existing allocation (required for 'update' or 'select' action)."
          },
          "components": {
            "type": "array",
            "description": "List of allocation filter components (required for 'create' or 'update' action). Can include components of type \"allocation_rule\" to reference existing allocation rules.",
            "items": {
              "required": [
                "key",
                "type",
                "values",
                "mode"
              ],
              "type": "object",
              "description": "A filter component used inside allocation rules.\nWhen the type is \"allocation_rule\", the component references existing allocation rules (nested allocation rules).\nA maximum nesting depth of 3 levels is supported, and circular references are not allowed.",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Key of an existing dimension. Examples: \"billing_account_id\", \"country\". When type is \"allocation_rule\", the key must be set to \"allocation_rule\".\nUse `GET /analytics/v1/dimensions` to retrieve all available dimensions."
                },
                "type": {
                  "description": "Dimension filter type for allocation rule components. See `DimensionsTypes` for per-value meanings. Allocation components do not support `allocation`, `attribution`, or `attribution_group` types.",
                  "type": "string",
                  "enum": [
                    "datetime",
                    "fixed",
                    "optional",
                    "label",
                    "tag",
                    "project_label",
                    "system_label",
                    "allocation_rule",
                    "gke",
                    "gke_label"
                  ],
                  "x-enumDescriptions": {
                    "fixed": "Standard built-in billing dimensions.",
                    "label": "Customer-defined resource labels; key is the label key.",
                    "tag": "AWS cost allocation tags; key is the tag key.",
                    "project_label": "Google Cloud project-level labels.",
                    "system_label": "DoiT- or provider-generated system labels.",
                    "optional": "Console grouping for label/tag keys; use a concrete subtype in filters.",
                    "datetime": "Time dimensions for date-based filtering.",
                    "allocation_rule": "Reference another allocation rule by ID.",
                    "gke": "Google Kubernetes Engine cost-allocation dimensions.",
                    "gke_label": "GKE workload labels."
                  }
                },
                "values": {
                  "type": "array",
                  "description": "Values to filter on. When type is \"allocation_rule\", the values are IDs of existing allocation rules.",
                  "items": {
                    "type": "string"
                  }
                },
                "inverse": {
                  "type": "boolean",
                  "description": "If true, all selected values will be excluded.",
                  "default": false
                },
                "includeNull": {
                  "type": "boolean",
                  "description": "Include null values.",
                  "default": false
                },
                "caseInsensitive": {
                  "type": "boolean",
                  "description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise.",
                  "default": false
                },
                "mode": {
                  "type": "string",
                  "description": "Filter mode to apply. When type is \"allocation_rule\", only \"is\" and \"contains\" modes are supported.",
                  "enum": [
                    "is",
                    "starts_with",
                    "ends_with",
                    "contains",
                    "regexp"
                  ]
                }
              }
            }
          },
          "formula": {
            "type": "string",
            "description": "Formula for combining components (A is the first component, B is the second one, etc.)",
            "example": "A AND B"
          }
        }
      }
    },
    "unallocatedCosts": {
      "type": "string",
      "description": "Custom label for values that do not fit into allocation (required for group type allocation).",
      "nullable": true
    },
    "folderId": {
      "type": "string",
      "description": "Identifier of the folder that contains the allocation. Set to \"root\" if the allocation is at the top level (not in a folder).",
      "default": "root",
      "example": "root"
    }
  }
}

Output​

OK - Allocation updated.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
idstringAllocation ID.
namestringAllocation name.
descriptionstringAllocation description.
typestringType of allocation (preset or custom).
allocationTypestringComposition type of allocation. One of: "single", "group".
createTimeinteger (int64)The time when the allocation was created (in UNIX timestamp).
updateTimeinteger (int64)Last time the allocation was modified (in UNIX timestamp).
anomalyDetectionbooleanWhether anomaly detection is enabled for this allocation. Only applicable to single allocations.
ruleobjectSingle allocation rule. Components can reference other existing allocation rules by using the "allocation_rule" dimension type.
rule.componentsarray of objectList of allocation filter components.
rule.components[].keystringKey of an existing dimension. Examples: "billing_account_id", "country". When type is "allocation_rule", the key must be set to "allocation_rule". Use GET /analytics/v1/dimensions to retrieve all available dimensions.
rule.components[].typestringDimension filter type for allocation rule components. See DimensionsTypes for per-value meanings. Allocation components do not support allocation, attribution, or attribution_group types. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "allocation_rule", "gke", "gke_label".
rule.components[].valuesarray of stringValues to filter on. When type is "allocation_rule", the values are IDs of existing allocation rules.
rule.components[].inversebooleanIf true, all selected values will be excluded. Default: false.
rule.components[].includeNullbooleanInclude null values. Default: false.
rule.components[].caseInsensitivebooleanIf true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise. Default: false.
rule.components[].modestringFilter mode to apply. When type is "allocation_rule", only "is" and "contains" modes are supported. One of: "is", "starts_with", "ends_with", "contains", "regexp".
rule.formulastringFormula for combining components (A is the first component, B is the second one, etc.).
rulesarray of object
rules[].namestringName of the allocation rule.
rules[].descriptionstringDescription of the allocation rule.
rules[].actionstringAction to perform with this rule. One of: "create", "update", "select".
rules[].idstringID of existing allocation (required for 'update' or 'select' action).
rules[].componentsarray of objectList of allocation filter components (required for 'create' or 'update' action). Can include components of type "allocation_rule" to reference existing allocation rules.
rules[].components[].keystringKey of an existing dimension. Examples: "billing_account_id", "country". When type is "allocation_rule", the key must be set to "allocation_rule". Use GET /analytics/v1/dimensions to retrieve all available dimensions.
rules[].components[].typestringDimension filter type for allocation rule components. See DimensionsTypes for per-value meanings. Allocation components do not support allocation, attribution, or attribution_group types. One of: "datetime", "fixed", "optional", "label", "tag", "project_label", "system_label", "allocation_rule", "gke", "gke_label".
rules[].components[].valuesarray of stringValues to filter on. When type is "allocation_rule", the values are IDs of existing allocation rules.
rules[].components[].inversebooleanIf true, all selected values will be excluded. Default: false.
rules[].components[].includeNullbooleanInclude null values. Default: false.
rules[].components[].caseInsensitivebooleanIf true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise. Default: false.
rules[].components[].modestringFilter mode to apply. When type is "allocation_rule", only "is" and "contains" modes are supported. One of: "is", "starts_with", "ends_with", "contains", "regexp".
rules[].formulastringFormula for combining components (A is the first component, B is the second one, etc.)
unallocatedCostsstringCustom label for values that do not fit into allocation (required for group type allocation).
folderIdstringIdentifier of the folder that contains the allocation. Set to "root" if the allocation is at the top level (not in a folder). Default: "root".
Raw JSON schema
{
  "type": "object",
  "description": "Allocation object, including rules and metadata.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Allocation ID."
    },
    "name": {
      "type": "string",
      "description": "Allocation name."
    },
    "description": {
      "type": "string",
      "description": "Allocation description."
    },
    "type": {
      "type": "string",
      "description": "Type of allocation (preset or custom)."
    },
    "allocationType": {
      "type": "string",
      "description": "Composition type of allocation.",
      "enum": [
        "single",
        "group"
      ]
    },
    "createTime": {
      "type": "integer",
      "description": "The time when the allocation was created (in UNIX timestamp).",
      "format": "int64"
    },
    "updateTime": {
      "type": "integer",
      "description": "Last time the allocation was modified (in UNIX timestamp).",
      "format": "int64"
    },
    "anomalyDetection": {
      "type": "boolean",
      "description": "Whether anomaly detection is enabled for this allocation. Only applicable to single allocations."
    },
    "rule": {
      "required": [
        "components",
        "formula"
      ],
      "type": "object",
      "description": "Single allocation rule. Components can reference other existing allocation rules by using the \"allocation_rule\" dimension type.",
      "nullable": true,
      "properties": {
        "components": {
          "type": "array",
          "description": "List of allocation filter components.",
          "items": {
            "required": [
              "key",
              "type",
              "values",
              "mode"
            ],
            "type": "object",
            "description": "A filter component used inside allocation rules.\nWhen the type is \"allocation_rule\", the component references existing allocation rules (nested allocation rules).\nA maximum nesting depth of 3 levels is supported, and circular references are not allowed.",
            "properties": {
              "key": {
                "type": "string",
                "description": "Key of an existing dimension. Examples: \"billing_account_id\", \"country\". When type is \"allocation_rule\", the key must be set to \"allocation_rule\".\nUse `GET /analytics/v1/dimensions` to retrieve all available dimensions."
              },
              "type": {
                "description": "Dimension filter type for allocation rule components. See `DimensionsTypes` for per-value meanings. Allocation components do not support `allocation`, `attribution`, or `attribution_group` types.",
                "type": "string",
                "enum": [
                  "datetime",
                  "fixed",
                  "optional",
                  "label",
                  "tag",
                  "project_label",
                  "system_label",
                  "allocation_rule",
                  "gke",
                  "gke_label"
                ],
                "x-enumDescriptions": {
                  "fixed": "Standard built-in billing dimensions.",
                  "label": "Customer-defined resource labels; key is the label key.",
                  "tag": "AWS cost allocation tags; key is the tag key.",
                  "project_label": "Google Cloud project-level labels.",
                  "system_label": "DoiT- or provider-generated system labels.",
                  "optional": "Console grouping for label/tag keys; use a concrete subtype in filters.",
                  "datetime": "Time dimensions for date-based filtering.",
                  "allocation_rule": "Reference another allocation rule by ID.",
                  "gke": "Google Kubernetes Engine cost-allocation dimensions.",
                  "gke_label": "GKE workload labels."
                }
              },
              "values": {
                "type": "array",
                "description": "Values to filter on. When type is \"allocation_rule\", the values are IDs of existing allocation rules.",
                "items": {
                  "type": "string"
                }
              },
              "inverse": {
                "type": "boolean",
                "description": "If true, all selected values will be excluded.",
                "default": false
              },
              "includeNull": {
                "type": "boolean",
                "description": "Include null values.",
                "default": false
              },
              "caseInsensitive": {
                "type": "boolean",
                "description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise.",
                "default": false
              },
              "mode": {
                "type": "string",
                "description": "Filter mode to apply. When type is \"allocation_rule\", only \"is\" and \"contains\" modes are supported.",
                "enum": [
                  "is",
                  "starts_with",
                  "ends_with",
                  "contains",
                  "regexp"
                ]
              }
            }
          }
        },
        "formula": {
          "type": "string",
          "description": "Formula for combining components (A is the first component, B is the second one, etc.).",
          "example": "A AND B"
        }
      }
    },
    "rules": {
      "type": "array",
      "items": {
        "required": [
          "action"
        ],
        "type": "object",
        "nullable": true,
        "description": "Allocation rule for a group type allocation. Components can reference other existing allocation rules by using the \"allocation_rule\" dimension type.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the allocation rule."
          },
          "description": {
            "type": "string",
            "description": "Description of the allocation rule."
          },
          "action": {
            "type": "string",
            "description": "Action to perform with this rule.",
            "enum": [
              "create",
              "update",
              "select"
            ]
          },
          "id": {
            "type": "string",
            "description": "ID of existing allocation (required for 'update' or 'select' action)."
          },
          "components": {
            "type": "array",
            "description": "List of allocation filter components (required for 'create' or 'update' action). Can include components of type \"allocation_rule\" to reference existing allocation rules.",
            "items": {
              "required": [
                "key",
                "type",
                "values",
                "mode"
              ],
              "type": "object",
              "description": "A filter component used inside allocation rules.\nWhen the type is \"allocation_rule\", the component references existing allocation rules (nested allocation rules).\nA maximum nesting depth of 3 levels is supported, and circular references are not allowed.",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Key of an existing dimension. Examples: \"billing_account_id\", \"country\". When type is \"allocation_rule\", the key must be set to \"allocation_rule\".\nUse `GET /analytics/v1/dimensions` to retrieve all available dimensions."
                },
                "type": {
                  "description": "Dimension filter type for allocation rule components. See `DimensionsTypes` for per-value meanings. Allocation components do not support `allocation`, `attribution`, or `attribution_group` types.",
                  "type": "string",
                  "enum": [
                    "datetime",
                    "fixed",
                    "optional",
                    "label",
                    "tag",
                    "project_label",
                    "system_label",
                    "allocation_rule",
                    "gke",
                    "gke_label"
                  ],
                  "x-enumDescriptions": {
                    "fixed": "Standard built-in billing dimensions.",
                    "label": "Customer-defined resource labels; key is the label key.",
                    "tag": "AWS cost allocation tags; key is the tag key.",
                    "project_label": "Google Cloud project-level labels.",
                    "system_label": "DoiT- or provider-generated system labels.",
                    "optional": "Console grouping for label/tag keys; use a concrete subtype in filters.",
                    "datetime": "Time dimensions for date-based filtering.",
                    "allocation_rule": "Reference another allocation rule by ID.",
                    "gke": "Google Kubernetes Engine cost-allocation dimensions.",
                    "gke_label": "GKE workload labels."
                  }
                },
                "values": {
                  "type": "array",
                  "description": "Values to filter on. When type is \"allocation_rule\", the values are IDs of existing allocation rules.",
                  "items": {
                    "type": "string"
                  }
                },
                "inverse": {
                  "type": "boolean",
                  "description": "If true, all selected values will be excluded.",
                  "default": false
                },
                "includeNull": {
                  "type": "boolean",
                  "description": "Include null values.",
                  "default": false
                },
                "caseInsensitive": {
                  "type": "boolean",
                  "description": "If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; rejected otherwise.",
                  "default": false
                },
                "mode": {
                  "type": "string",
                  "description": "Filter mode to apply. When type is \"allocation_rule\", only \"is\" and \"contains\" modes are supported.",
                  "enum": [
                    "is",
                    "starts_with",
                    "ends_with",
                    "contains",
                    "regexp"
                  ]
                }
              }
            }
          },
          "formula": {
            "type": "string",
            "description": "Formula for combining components (A is the first component, B is the second one, etc.)",
            "example": "A AND B"
          }
        }
      }
    },
    "unallocatedCosts": {
      "type": "string",
      "description": "Custom label for values that do not fit into allocation (required for group type allocation).",
      "nullable": true
    },
    "folderId": {
      "type": "string",
      "description": "Identifier of the folder that contains the allocation. Set to \"root\" if the allocation is at the top level (not in a folder).",
      "default": "root",
      "example": "root"
    }
  }
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
40420RESOURCE_NOT_FOUNDThe requested resource does not exist. Check the identifier argument.

Aliases: updateallocation