Getting Started
Welcome
CloudHealth provides two APIs for programmatically interacting with the platform: a REST API and a GraphQL API. You are currently viewing the documentation for the REST API. To access the documentation for the GraphQL API, click here.
Welcome to the CloudHealth REST API Guide. Here you’ll find API services that programmatically retrieve data from the CloudHealth Platform. The CloudHealth REST API has predictable, resource-oriented URLs, and it uses HTTP response codes to indicate API errors. All API responses, including errors, return JSON.
This API continues to be under development and will evolve. CloudHealth sends information on additions and changes to the API in the Product Updates emails that go out to all customers.
For user guides, FAQs, and product updates, visit the CloudHealth Help Center.
How to Use the CloudHealth API
The goal of the CloudHealth API is to let you write your own applications that leverage and extend CloudHealth functionality.
The CloudHealth API provides programmatic access to functionalities in the CloudHealth platform using REST-based arguments and JSON-formatted responses.
You send REST API requests to various endpoints to retrieve and update data from the CloudHealth Platform. Different API functionality can be found at different endpoints. Here are some example endpoints.
https://chapi.cloudhealthtech.com/olap_reports/cost/history
https://chapi.cloudhealthtech.com/v1/perspective_schemas
Using the API, you can query the following areas of the CloudHealth Platform.
- Reporting
- Asset
- Account
- Metrics
- Tagging
- Perspectives
- Partner
- Partner Customer Provisioning
- Partner AWS Account Assignment
- Customer Statement
Anatomy of a Request
Here’s a REST-based request that uses the CloudHealth API.
curl -H 'Authorization: Bearer XXXXX98900000YYYY' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/cost/history?interval=monthly'
Let’s break down this request.
cURL
is a command-line REST client (https://curl.haxx.se).- The
-H
flags represent the headers that you need to pass with each request. There are two headers that each request must contain:-H 'Authorization: Bearer XXXXX98900000YYYY'
is the authorization header. It attaches your unique API key to the request. Here,XXXXX98900000YYYY
is your API Key. See How CloudHealth Validates API Requests.- H 'Accept: application/json'
is the communication header. You can also specify this header as-H 'Content-Type:application/json'
.- The optional header
Accept-Encoding:gzip
compresses the communication with GZIP compression.
https://chapi.cloudhealthtech.com/olap_reports/cost/history
is the REST endpoint. In this example, the endpoint returns data for the Standard Cost History Report.- If you prefer to pass your API key as a query parameter, instead of using an authorization header, use
api_key=XXXXX98900000YYYY
to attach your unique API key with the request. Here,XXXXX98900000YYYY
is your API Key. interval=monthly
is a query parameter that you append to the REST endpoint. Query parameters allow you to constrain the data returned from a request. You can attach multiple query parameter as long as each parameter is separated from the next by the&
symbol.- A URI string is made up of the REST endpoint and all the query parameters attached to it. In this example, this is the URI string.
https://chapi.cloudhealthtech.com/olap_reports/cost/history?interval=monthly
The maximum permissible length of a URI string is 4000 characters.
Types of Requests
- GET requests retrieve data from the CloudHealth Platform.
curl 'https://chapi.cloudhealthtech.com/olap_reports/cost/history?interval=monthly' -H 'Authorization: Bearer XXXXX98900000YYYY' -H 'Accept: application/json'
-
POST requests send data to the CloudHealth Platform. They include a JSON-formatted message body, which contains the data that should be sent. Here, the message body is specified as a parameter following the
-d
flag. -
The
Content-Type: application/json
header is required when PUTting or POSTing JSON to the API, else an HTTP 422 Unprocessable Entity is issuedcurl 'https://chapi.cloudhealthtech.com/v1/perspective_schemas' -H 'Authorization: Bearer XXXXX98900000YYYY' -H 'content-type: application/json' -d '{ "schema":{ "name":"Environment-API", "rules":[{"type":"categorize","asset":"AwsAsset","tag_field":["cht_env"],"ref_id":"206159110488","name":"Env"}], "merges":[], "constants":[…]} }'
All examples in the CloudHealth REST API documentation have been tested on the Git Bash shell terminal. To use the examples in the Windows Command prompt, replace the single quotes in the curl request with double quotes. For example:
curl -H "Authorization: Bearer XXXXX98900000YYYY" -H "Accept: application/json" "https://chapi.cloudhealthtech.com/olap_reports/cost/history?interval=monthly"
This area displays code examples that you can copy and paste into a terminal. Before running these examples, make sure you replace placeholder values enclosed within angle brackets <> with actual values.
For example, all API queries must include your unique API Key in the authorization header. The value of this key is indicated as <your_api_key> in these code examples. Replace this placeholder value with your actual API Key.
Getting Your API Key
Instructions on how to get your unique API Key for authenticating CloudHealth API calls.
How CloudHealth Validates API Requests
You need an API Key in order to make authenticated requests to the CloudHealth API service.
An API Key is a globally unique identifier (GUID) that CloudHealth generates for each user in the platform. When you make an API request, this GUID uniquely identifies and authenticates you as the originator of the request.
To request an API key, click on My Profile in your user settings.
In your profile settings, scroll to the API Key section and click Get API Key. Then click Save Profile Changes.
Include this GUID with each API request to authenticate into the CloudHealth platform.
Periodic Key Rotation
While securing your API Key is important, it is also essential to periodically rotate your API key for security reasons. To update your key, return to your profile settings and click Get API Key to create a new one. Then click Save Profile Changes. When you generate an API Key, the previous key becomes invalid.
The API enforces all the same authentication and authorization checks as the CloudHealth Platform. Therefore, users in an organization can only see data scoped to their organization. Additionally, the API enforces any restrictions to user roles.
Error Codes
Types of response codes that indicate the success or failure of a CloudHealth API request.
CloudHealth uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx
range indicate success, codes in the 4xx
range indicate an error that failed given the information provided, and codes in the rare 5xx
range indicate an error with CloudHealth’s servers.
Code | Name | Description |
---|---|---|
200 | OK | Success |
201 | OK | Success |
204 | OK | Success |
400 | Bad Request | Header missing |
401 | Unauthorized | Currently logged out |
403 | Forbidden | Bad API Key |
404 | Not Found | Bad endpoint |
408 | Request Timeout | Exceeding read timeout |
422 | Unprocessable Entity | Input format error |
429 | Too many requests | Exceeding post rate limit |
500 | Internal Service Error | General error |
503 | Service not available | Back end capped out |
All errors return JSON in the following format:
{
"error": "error message here"
}
AWS Accounts in CloudHealth
Enable AWS Account
Enable an AWS Account in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/aws_accounts
Parameters
-
namerequired
String that specifies the unique display name of an AWS account.
-
authenticationrequired
JSON field that specifies how to authenticate with your AWS accounts. Use IAM Role (recommended) or IAM User (less secure) to authenticate.
-
protocolrequired
Authentication protocol. Specify
access_key
orassume_role
-
access_keyrequired
Access Key for IAM User
-
secret_keyrequired
Access Key for IAM User
-
assume_role_arnrequired
Role ARN for IAM Role
-
assume_role_external_idrequired
External ID generated by CloudHealth. See How to get External ID.
-
-
billing
JSON field that specifies the location of the AWS Detailed Billing Record (DBR).
-
bucketrequired
Name of S3 bucket containing the DBR
-
-
cost_and_usage_report
JSON field that specifies the location of the AWS Cost and Usage Report (CUR).
-
bucketrequired
Name of S3 bucket containing the CUR
-
path
The path to the CUR report, including the prefix
-
-
cloudtrail
JSON field that specifies whether CloudHealth should collect CloudTrail Trails and the location of Trail files.
-
enabledrequired
Should CloudHealth collect CloudTrail trails? Default value is
False
-
bucketrequired
Name of S3 bucket containing the files
-
prefixrequired
Prefix of Trail files
-
-
cloudwatch
JSON field that specifies whether CloudHealth should collect CloudWatch data.
-
enabledrequired
Boolean that specified whether CloudHealth collect AWS CloudWatch data. Default value is
True
-
namespaces
String that specifies the namespaces from which CloudWatch data should be gathered. Value can be
CWAgent
,System/Linux
,System/Windows
, or a comma-separated list of two or more of these values. Default value is an empty string. -
runtime
Number that specifies the frequency in hours at which CloudHealth should gather CloudWatch data. Default value is
1
. Value can be1
or24
.
-
-
tags
JSON array that specifies key-value pairs for tags. When you use this field, The API restricts queries to AWS accounts that are tagged with these key-value pairs.
-
keyrequired
Tag key
-
valuerequired
Tag value
-
-
hide_public_fields
Boolean field that specifies whether CloudHealth should store public DNS and IP. Default value is
True
-
region
JSON field that specifies the type of AWS Account. Value can be
global
(default) orgovcloud
. -
primary_aws_region
String that specifies which region should be used to validate the read-only IAM policy. Value can be
us-east-1
(default) oreu-central-1
for global AWS accounts. GovCloud customers cannot modify their default AWS region,us-gov-west-1
. -
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
Result header contains Location: https://chapi.cloudhealthtech.com/v1/aws_accounts/1
{
"name": "Production Account",
"authentication": {
"protocol": "assume_role",
"assume_role_arn": "arn:aws:iam::XCXXXXXXXXXZ:role/CloudHealth-IAM-Role",
"assume_role_external_id": "ABCDEFGH1234"
},
"billing": {
"bucket": "my-billing-bucket"
},
"cost_and_usage_report": {
"bucket": "cur-bucket",
"path": "cur/path/api"
},
"cloudtrail": {
"enabled": true,
"bucket": "my-cloudtrail-bucket"
},
"tags": [
{"key": "Environment", "value": "Production"}
]
}
{
"id": 1,
"name": "Production Account",
"hide_public_fields": false,
"region": "global",
"created_at": "2015-12-16T23:03:49Z",
"updated_at": "2015-12-16T23:03:49Z",
"account_type": "Unknown",
"status": {
"level": "unknown"
},
"authentication": {
"protocol": "assume_role",
"assume_role_arn": "arn:aws:iam::XCXXXXXXXXXZ:role/CloudHealth-IAM-Role",
"assume_role_external_id": "ABCDEFGH1234"
},
"billing": {
"bucket": "my-billing-bucket",
"is_consolidated": false
},
"cost_and_usage_report" : {
"bucket": "cur-bucket",
"path": "cur/path/api"
},
"cloudtrail": {
"enabled": true,
"bucket": "my-cloudtrail-bucket"
},
"cloudwatch": {
"enabled": true,
"namespaces": "CWAgent,System/Linux,System/Windows",
},
"tags": [
{
"key": "Environment",
"value": "production"
}
],
"_links": {
"self": {
"href": "/v1/aws_accounts/1"
}
}
}
curl -d
'{
"name": "Production Account",
"authentication": {
"protocol": "access_key",
"access_key": "AKIAQQQQQQQQQQQ",
"secret_key": "S87345j34lkj3l45lkj+2342"
},
"billing": {
"bucket": "my-billing-bucket"
},
"cost_and_usage_report" : {
"bucket": "cur-bucket",
"path": "cur/path/api"
},
"cloudtrail": {
"enabled": true,
"bucket": "my-cloudtrail-bucket"
},
"tags": [{
"key": "Environment",
"value": "Production"
}]
}'
-H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' --request POST 'https://chapi.cloudhealthtech.com/v1/aws_accounts'
AWS Accounts in CloudHealth
Get a list of all AWS Accounts that are enabled in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/aws_accounts
Parameters
-
page
Specify the page number for results
-
per_page
Specify how many results should be displayed per page. Default value is 30. Maximum value is 100.
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
The results of this API call are paginated.
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts"
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts?page=2"
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts?page=3&per_page=100"
Single AWS Account
Get information on a single AWS Account that is enabled in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/aws_accounts/:id
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts/<account_ID>"
Update Existing AWS Account
Update the attributes of an AWS Account that is already enabled in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/aws_accounts/:id
Parameters
-
namerequired
String that specifies the unique display name of an AWS account.
-
authentication
JSON field that specifies how to authenticate with your AWS accounts. Use IAM Role (recommended) or IAM User (less secure) to authenticate.
-
protocolrequired
Authentication protocol. Specify
access_key
orassume_role
-
access_keyrequired
Access Key for IAM User
-
assume_role_arnrequired
Role ARN for IAM Role
-
assume_role_external_idrequired
External ID generated by CloudHealth
-
-
billing
JSON field that specifies the location of the AWS Detailed Billing Record (DBR)
-
bucketrequired
Name of S3 bucket containing the DBR
-
-
cost_and_usage_report
JSON field that specifies the location of the AWS Cost and Usage Report (CUR).
-
bucketrequired
Name of S3 bucket containing the CUR
-
path
The path to the CUR report, including the prefix
-
-
cloudtrail
JSON field that specifies whether CloudHealth should collect CloudTrail Trails and the location of Trail files.
-
enabledrequired
Should CloudHealth collect CloudTrail trails? Default value is
False
-
bucketrequired
Name of S3 bucket containing the files
-
prefixrequired
Prefix of Trail files
-
-
cloudwatch
JSON field that specifies whether CloudHealth should collect CloudWatch data.
-
enabledrequired
Should CloudHealth collect AWS Config files? Default value is
True
-
namespaces
String that specifies the namespaces from which CloudWatch data should be gathered. Value can be
CWAgent
,System/Linux
,System/Windows
, or a comma-separated list of two or more of these values. Default value is an empty string. -
runtime
Number that specifies the frequency in hours at which CloudHealth should gather CloudWatch data. Default value is
1
. Value can be1
or24
.
-
-
tags
JSON field that specifies key-value pairs for tags. When you use this field, The API restricts queries to AWS accounts that are tagged with these key-value pairs.
-
keyrequired
Tag key
-
valuerequired
Tag value
-
-
hide_public_fields
Boolean field that specifies whether CloudHealth should store public DNS and IP. Default value is
True
-
region
JSON field that specifies the type of AWS Account. Value can be
global
(default) orgovcloud
. -
primary_aws_region
String that specifies which region should be used to validate the read-only IAM policy. Value can be
us-east-1
(default) oreu-central-1
for global AWS accounts. GovCloud customers cannot modify their default AWS region,us-gov-west-1
.
{
"name": "Production Engineering Account",
"tags": [
{
"key": "Environment",
"value": "production"
},
{
"key": "Owner",
"value": "Engineering"
}
]
}
curl -d '{"authentication":{"protocol":"assume_role","assume_role_arn":"arn:123","assume_role_external_id":"61a1XXXXXXXXXXXXXXXXXXXXX5d8c6"},"name":"Tools 123"}' -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -H 'Accept: application/json' --request PUT 'https://chapi.cloudhealthtech.com/v1/aws_accounts/<account_id>'
Delete AWS Account
Delete an AWS Account from the CloudHealth Platform
https://chapi.cloudhealthtech.com/v1/aws_accounts/:id
curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/aws_accounts/:id'
Get External ID
Generate your unique customer External ID so that you can configure an IAM Role in the AWS Console.
https://chapi.cloudhealthtech.com/v1/aws_accounts/:id/generate_external_id
You cannot generate and specify your own External ID as the value of the assume_role_external_id
parameter.
CloudHealth generates a unique External ID for each customer. You can only use this ID as the value of the assume_role_external_id
parameter.
Because the CloudHealth-generated ID is unique to you, you can reuse it across all your accounts.
To get your External ID, log into the CloudHealth Platform. From the left menu, select Setup > Accounts > AWS and click New Account. The account setup form displays the generated External ID.
You can also get your API key through an endpoint.
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/v1/aws_accounts/:id/generate_external_id"
SSO Configuration
Configure SSO
Create or update SSO configuration in the CloudHealth platform.
https://chapi.cloudhealthtech.com/v1/sso/configure
Parameters
-
client_api_id
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
-
sso_providerrequired
String that specifies the unique display name of an AWS account. Specify
ah-saml
(AuthHub SAML), orah-waad
(AuthHub Azure AD). -
issuerrequired
String that specifies the SAML Issuer or Entity ID.
-
domainsrequired
Array that specifies SSO domains, with each domain specified in
company.com
format. -
default_organization_id
Number that specifies the ID of the default organization to which new users should be assigned.
-
sign_in_endpointrequired
String that specifies the SAML 2.0 Endpoint from your IdP.
-
signing_certrequired
String that specifies the contents of the X.509 certificate from your IdP.
-
sso_ignore_idp_organizationrequired
Boolean that specifies whether the IdP does not support passing the organization to which a new user should be assigned. Default value is
false
. -
azure_ad_roles_protocolrequired
Boolean that specifies whether the Azure Roles protocol is used to pass roles to the CloudHealth platform. Default value is
true
.
curl -X PUT -H 'Authorization: Bearer API_KEY' -H 'Content-Type: application/json' -d '{"sso_provider": <"ah-samlp"|"ah-waad">, "domains": ["<domain-1>,...,<domain-N>"], "signing_cert": "<cert>", "sign_in_endpoint": "<sign_in_endpoint>", "issuer": "<issuer>", "sso_ignore_idp_organization": <true|false>}' 'https://chapi.cloudhealthtech.com/v1/sso/configure'
{"identityProviderId":"<idp-guid>","verifyCertAlias":"cloudhealth-<id>","samlMDidpRedirectBindingURL":"<sign_in_endpoint>","issuer":"<issuer>","cert":"<cert>","message":"SSO configured for <customer>"}
Retrieve SSO configuration
Retrieve an existing SSO configuration
https://chapi.cloudhealthtech.com/v1/sso/configuration
Parameters
-
client_api_id
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
curl -X GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/sso/configuration'
{"configuration":{"sso_provider":"google-apps", "claimed_domains":["cloudhealthtech.com"], "pending_domains":[], "connection_name":"cloudhealthtech-com", "default_organization":"CloudHealth Technologies"} }
Delete SSO configuration
Delete an existing SSO configuration
https://chapi.cloudhealthtech.com/v1/sso/unconfigure
Parameters
-
client_api_id
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
curl -X DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/sso/unconfigure'
{"success":"SSO unconfigured for CloudHealth Technologies"}
Retrieve Pending SSO Domains
Retrieve SSO domains that are awaiting validation
https://chapi.cloudhealthtech.com/v1/sso/pending_domain_claims
Parameters
-
client_api_id
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
curl -X GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/sso/pending_domain_claims'
{"pending_sso_domains": [{"domain":"cloudhealthtech.com", "token":"xxxxx-xxxxx-xxxxx", "created_at":"2019-07-10T18:45:47Z", "created_by_id":11937}]}
Validate Pending SSO Domains
Validate SSO domains that are pending
https://chapi.cloudhealthtech.com/v1/sso/validate_pending_domain_claim
Parameters
-
client_api_id
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
-
pending_domain_namerequired
String that specifies the domain to validate in
company.com
format.
curl -X PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d '{"pending_domain_name":"cloudhealthtech.com"}' 'https://chapi.cloudhealthtech.com/v1/sso/validate_pending_domain_claim'
{"valid":"true" }
Perspectives
Introduction to Perspectives API
An introduction to the Perspectives API.
The Perspectives API allows you to manipulate a schema file that defines the rules for grouping assets in a Perspective. Use the following endpoint:
https://chapi.cloudhealthtech.com/v1/perspective_schemas
Using a schema file as a payload, you can perform these operations:
- Create Perspectives
- Modify rules that govern how Perspective Groups are created
- Merge Groups
- Reorder Groups
- Delete Perspectives
Understand Format of Perspectives Schema
Learn about the Perspective Schema Format.
Parameters
-
name
String that specifies the name of the Perspective. The name need not match the name of an existing (active or archived) Perspective.
-
include_in_reports
Boolean that specifies whether the Perspective is included in CloudHealth Reports. Specify as
true
(default) orfalse
. -
rules
An array of rules (objects) that govern Perspective membership. The ordering of the rules matters. Rules are evaluated in order starting from the first one in the array. This parameter simplifies the process of reordering a Group. Run a read operation to get the schema of a Perspective, change the order in the schema in a text editor, and upload the modified schema to the same Perspective.
-
merges
List of merge objects, which can be of type Dynamic Group or Dynamic Group Block. The Dynamic Group merge allows for two Groups to merged and the Dynamic Block Group is to merge two entire blocks of Groups. Each merge specifies a list of source objects and a single target object (Groups or blocks), where the sources are to be merged into the target.
-
constants
List of reference objects that refer to Groups, blocks, and assets that are specified in rules. When a schema is retrieved through a GET operation, every Group (dynamic and static) is listed in the this section. Although meant mainly for reference, constants can be modified to change the name of Groups and blocks. The full list of potential constant types is provided below.
Constant Types can either be Dynamic Group
, Static Group
, or an asset type listed below.
Expansion types such as
AwsAsset
orAzureTaggableAsset
are not included.
- AwsAccount
- AwsAvailabilityZone
- AwsGroup
- AwsImage
- AwsInstance
- AwsInstanceReservation
- AwsInstanceStatus
- AwsInstanceType
- AwsRdsInstance
- AwsRegion
- AwsSecurityGroup
- AwsSecurityGroupRule
- AwsSnapshot
- AwsSpotRequest
- AwsTag
- AwsUser
- AwsVolume
- ChefAccount
- ChefCookbook
- ChefCookbookVersion
- ChefNode
- AwsS3Bucket
- AwsCloudFormationStack
- AwsCloudFormationResource
- ChefCookbookConstraint
- ChefEnvironment
- AwsRdsSnapshot
- AwsVpc
- AwsRedshiftCluster
- AwsRedshiftSnapshot
- AwsRedshiftReservedNode
- AwsVpcSubnet
- AwsLoadBalancer
- AwsDynamoDbTable
- AwsCacheCluster
- InstanceAttributeHash
- InstanceFileSystem
- AwsRdsInstanceReservation
- AwsRdsSecurityGroup
- AwsRdsSecurityGroupRule
- AwsRdsSubnetGroup
- AwsInstanceReservationModification
- AwsInstanceReservationModificationItem
- AwsEmrCluster
- AwsEmrClusterInstanceGroup
- AwsEmrClusterInstance
- AwsInstanceReservationListing
- PagerdutyAccount
- PagerdutyIncident
- AwsNaclTable
- AwsNaclRule
- AwsCustomerGateway
- AwsVpnGateway
- AwsVpnConnection
- AwsInternetGateway
- AwsEni
- AwsElasticIp
- AwsEipPrivateIp
- Alert
- GcpComputeRegion
- GcpComputeZone
- GcpComputeProject
- GcpComputeMachineType
- GcpComputeInstance
- GcpComputeDiskType
- GcpComputeDisk
- GcpComputeSnapshot
- GcpComputeImage
- GcpComputeAttachedDisk
- GcpComputeMachineTypeProfile
- GcpTag
- GcpBillingStatement
- GcpBillingStatementItem
- GcpUsageStatement
- GcpStorageBucket
- VmwareAccount
- VmwareFolder
- VmwareDatacenter
- VmwareHost
- VmwareDatastore
- VmwareVirtualMachine
- VmwareCustomField
- DockerImage
- DockerContainer
- DelegatedAction
- CloudFrontDistribution
- CloudFrontOrigin
- DataCenterAccount
- DataCenterServer
- DataCenterServerFileSystem
- AzureEnrollment
- AzureBillingStatementItem
- AzureStoredBill
- AzureVm
- DataCenterServerNetworkInterface
- DataCenterServerCpu
- DataCenterServerBlockDevice
- AlertlogicAccount
- AwsRoute53HostedZone
- AnsibleAccount
- AnsibleNode
- AwsConfigRule
- AwsConfigRuleEvaluationResult
- AwsElasticacheReservedNode
- DatadogAccount
- DatadogHost
- DatadogTag
- AzureSubscription
- AzureTag
- AwsLambdaFunction
- AzureAccount
- AzureDepartment
- AzureCostCenter
- NewrelicAccount
- NewrelicServer
- IntegrationTag
- AzureZone
- AzureRegion
- AzureResourceGroup
- AzureServicePrincipal
- AzureVmFileSystem
- AzureVmNetworkInterface
- AzureVmCpu
- AzureVmVirtualDisk
- AzureVmSize
- AzureCatalog
- AzureVmRate
- AzureOffer
- AzureRateCard
- AzureStoredUsage
- AwsIamPolicy
- AwsIamRole
- AwsIamServerCertificate
- AwsAdsAgentStat
- AwsAdsServer
- AwsAccountRegionAttribute
- AwsAdsProcess
- AwsAdsConnection
- DataCenterTag
- CustomerTag
- AwsIamCredentialReport
- AzureCloudService
- AzureSecurityGroup
- AzureSecurityRule
- AzureIpAddress
- AwsIamPasswordPolicy
- AzureStorage
- AzureVmScaleSet
- AwsCloudtrailTrail
- AzureSqlServer
- AzureSqlDatabase
- AzurePartnerCenter
- AzureRedisCache
- JiraAccount
- IntegrationOauthAccount
- AzurePartnerCustomer
- IntegrationMetadata
- AzureVirtualNetworkGateway
- AzureAppServicePlan
- AzureServiceBusNamespace
- AzureVirtualNetwork
- AzureBatchAccount
- AzureBackupVault
- AzureRecoveryServicesVault
- AzureHdInsightCluster
- AzureSearchService
- AzureSqlDataWarehouse
- AzureStorSimpleDeviceManager
- AzureAppService
- AzureLogAnalyticsWorkspace
- AzureExpressRouteCircuit
- AzureCdnProfile
- AwsNatGateway
- AzureSnapshot
- AzureNetworkInterface
- AzureManagedDisk
- AzureAppInsight
- AwsElasticFileSystem
- AzureDocumentDb
- AzureKeyVault
- AwsElasticsearchDomain
- AwsElasticsearchInstance
- AwsElasticsearchVolume
- AwsDedicatedHost
- AzureApplicationGateway
- AwsConfigSetting
- AwsWorkspace
- AzureAppServiceEnvironment
- AwsAutoScalingGroup
- AwsKinesisStream
- AzureVmReservationRate
- AzureReservationOrder
- AzureReservation
- AzureVmRiQuote
How to Get Perspective ID
In order to perform Get, Put, and Post operations using this API, you need to provide the ID of the Perspective that you want to manipulate.
You can get the ID of a Perspective from the CloudHealth Platform. From the left menu, select Setup > Perspectives and click the Perspective that you want to manipulate. The ID of the Perspective appears in the browser URL. Here’s an example URL:
https://apps.cloudhealthtech.com/perspectives/35261XXX012
Here, 35261XXX012
is the Perspective ID.
Retrieve All Perspectives
Retrieve a list of all Perspectives you have created in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/perspective_schemas
Parameters
-
active_only
Boolean that specifies whether only active Perspectives are returned in the response.
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
The response contains the list in the form of a hash that includes the Perspective ID, Perspective name, and a flag field that indicates whether the Perspective is active.
curl -s -H "Accept: application/json" "https://chapi.cloudhealthtech.com/v1/perspective_schemas?api_key=<api key>"
{
"206159639971": { "name": "DDE Test", "active": false },
"206159351171": { "name": "Environment ", "active": true },
"206159659286": { "name": "Environment-tmp", "active": false },
"206159657643": { "name": "Efe Test", "active": false },
"206159708697": { "name": "Sidd test", "active": true },
"181": { "name": "Function", "active": true },
"650": { "name": "Finance Costs", "active": true }
}
Retrieve Perspective Schema
Retrieve the schema that defines a specific Perspective. Identify the specific Perspective by its ID. See How to Get Perspective ID.
https://chapi.cloudhealthtech.com/v1/perspective_schemas/:perspective-id
Parameters
-
include_version
Boolean that defines whether the current version of the perspective is returned in the response.
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
curl -s -H "Accept: application/json" "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>?api_key=<api_key>"
{
"schema": {
"name": "Environment",
"include_in_reports": "true",
"rules": [
{
"type": "categorize",
"asset": "AwsAsset",
"tag_field": [
"cht_env"
],
"ref_id": "5841XXXXXXX853",
"name": "AWS Assets"
},
{...}
],
"merges": [
{
"type": "Group",
"to": "584XXXXX39263",
"from": [
"584YYYYYY9283"
]
},
{...}
],
"constants": [
{
"type": "Dynamic Group Block",
"list": [
{
"ref_id": "ABCDEFG522853",
"name": "AWS Assets"
},
{...}
]
},
{...}
]
}
}
curl -s -H "Accept: application/json" "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>?api_key=<api_key>" | python -m json.tool
Create Perspective Schema
Create a Perspective and associate it with a new schema. The ID of the new Perspective is returned in the message field in the POST response.
https://chapi.cloudhealthtech.com/v1/perspective_schemas/
Parameters
-
include_version
Boolean that defines whether the current version of the perspective is returned in the response.
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
-
client_api_id
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
How to Duplicate a Perspective
To duplicate a Perspective, retrieve the schema from the source Perspective (e.g., Perspective A) and POST that schema with a new name (e.g., Perspective B) to create a duplicate of Perspective A. All references in the schema rules to existing groups and blocks in Perspective A are seen as directives to create corresponding groups in Perspective B. Perspective A and its Groups remain unchanged.
How to Add a Perspective Group
When creating a Perspective, if your schema contains a reference to a Group that does not exist within the Perspective, the POST call creates that Group in the Perspective. Therefore, if there are rules in your schema that reference a Group that does not exist in the Perspective, the POST call creates that new Group and associates those rules with the newly created Group.
For example, this POST call creates a Perspective:
curl -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/v1/perspective_schemas?api_key=<api_key>" -d '{"schema":{"name":"Test 1000002","rules":[{"type":"filter","asset":"AwsInstance","to":"new group 1","condition":{"clauses":[{"field":["Active?"],"op":"=","val":"true"}]}},{"type":"filter","asset":"AwsInstance","to":"new group 1","condition":{"clauses":[{"field":["First Discovered"],"op":">","val":"2016-01-04T23:19:34+00:00"}]}}],"constants":[],"merges":[]}'
When you make a subsequent GET call to retrieve this schema, a new group (Group-1) is created and displayed in the response. All references to new group 1
in the schema are converted into references to the newly created group.
curl -s -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/v1/perspective_schemas/?api_key=<api_key>" -d '{"schema": {"name": "Environment","include_in_reports": "true",
"rules": [{"type": "categorize","asset": "AwsAsset","tag_field": ["cht_env"],"ref_id": "5841XXXXXXX853","name": "AWS Assets"}],
"merges": [{"type": "Group","to": "584XXXXX39263","from": ["584YYYYYY9283"]}],
"constants": [{"type": "Dynamic Group Block","list": [{"ref_id": "ABCDEFG522853","name": "AWS Assets"}],
}}'
Update Perspective Schema
Modify a Perspective based on rules posted through a schema.
https://chapi.cloudhealthtech.com/v1/perspective_schemas/:perspective-id
Parameters
-
check_version
Number that specifies the version of the Perspective schema that should be updated.
-
include_version
Boolean that defines whether the current version of the perspective is returned in the response.
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
If the schema contains references to Groups that do no exist in the Perspective, the PUT operation creates those Groups in the Perspective.
You can specify both to
and from
fields in rules that reference target Groups. The from
field is optional. When it is not present, the Other (Assets Not Allocated)
group is considered to be the from
Group.
When you create a group-to-group rule, the update/create calls verify that the source group already has at least one rule higher in the rule that targets it.
How to Avoid Conflicts during Concurrent Updates
Use the check_version
parameter to ensure that a concurrent update is not overwritten.
curl -s -H 'Content-Type: application/json' -X PUT "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>?api_key=<api_key>&check_version=3"
If the Perspective was updated, and therefore version-incremented, since the last GET operation, the update request returns a 400
error.
How to Remove a Static Group from a Perspective
To remove a static group from a perspective, remove the rules targeting that group from the schema.
In this example, the static group Group To Delete
will be removed from the perspective, and Group to Keep
will not be removed. The following example shows what the schema looks like before the group is removed from the perspective:
{
"name": "RemoveStaticGroup",
"rules": [
{
"type": "filter",
"asset": "Group To Keep",
"to": "123456789",
"condition": {
"clauses": [
{
"field": [
"Active?"
],
"op": "=",
"val": "true"
}
]
}
},
{
"type": "filter",
"asset": "Group To Delete",
"to": "2468101214",
"condition": {
"clauses": [
{
"field": [
"Active?"
],
"op": "=",
"val": "false"
}
]
}
}
],
"merges": [
],
"constants": [
{
"type": "Static Group",
"list": [
{
"ref_id": "123456789",
"name": "KeepMe"
},
{
"ref_id": "2468101214",
"name": "DeleteMe"
},
{
"ref_id": "13579131517",
"name": "Other",
"is_other": "true"
}
]
}
],
"include_in_reports": "false"
}
After the group is removed, the schema no longer lists the Group to Delete
:
{
"name": "AfterRemovingStaticGroup",
"rules": [
{
"type": "filter",
"asset": "Group To Keep",
"to": "123456789",
"condition": {
"clauses": [
{
"field": [
"Active?"
],
"op": "=",
"val": "true"
}
]
}
},
"merges": [
],
"constants": [
{
"type": "Static Group",
"list": [
{
"ref_id": "123456789",
"name": "KeepMe"
},
{
"ref_id": "13579131517",
"name": "Other",
"is_other": "true"
}
]
}
],
"include_in_reports": "false"
}
curl -s -H 'Content-Type: application/json' -X PUT "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
?api_key=<api_key>" -d '{"schema":<schema JSON>}'
Delete Perspective Schema
Remove a specific Perspective from the CloudHealth Platform. You can perform a soft (default), forced, or hard deletion.
https://chapi.cloudhealthtech.com/v1/perspective_schemas/:perspective-id
Parameters
-
force
Boolean that specifies whether the Force Delete option is exercised. See Force Delete.
-
hard_delete
Boolean that specifies whether the Hard Delete option is exercised. See Hard Delete.
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
There are three levels of Perspective deletion.
Soft Delete (default)
This option deletes the Perspective and archives it only if there are no Perspective dependencies such as Policies and Report Subscriptions. You can restore the deleted Perspective.
curl -s -H "Accept: application/json" -XDELETE "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>?api_key=<api_key>"
Force Delete
This option deletes and archives the Perspective irrespective of whether any dependencies exist in Policies or Report Subscriptions. You can restore the deleted Perspective, but you will need to recreate the Policies and Report Subscriptions that depended on the Perspective.
curl -s -H "Accept: application/json" -XDELETE "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
?api_key=<api_key>
&force=true"
Hard Delete
This option deletes the Perspective without archiving it. You cannot restore a Perspective that was deleted using this option.
curl -s -H "Accept: application/json" -XDELETE "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective id>
?api_key=<api_key>
&force=true
&hard_delete=true"
curl -s -H "Accept: application/json" -XDELETE "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
?api_key=<api_key>"
Get Perspective Version
Include the version of a Perspective in the response.
curl -s -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json'
"https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>
?&include_version=true"
{
"type": "Version",
"list": [
{
"ref_id": 181,
"val": 2
}
]
}
Add Dynamic Group to Perspective
Add a dynamic group to an existing Perspective. You can exclude the ref_id
field from the request. Alternately, if you include the ref_id
field, specify an arbitrary numerical value for it.
curl -s -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -X PUT "https://chapi.cloudhealthtech.com/v1/perspective_schemas/<perspective_id>" -d '{"schema":{"name": "<perspective_name>","rules": [{"type": "categorize","asset": "AwsS3Bucket","field": ["Active?"],"name": "Dynamic_group_name"}]}}''
Reporting
Introduction to Reporting API
An introduction to the Reporting API and common terminology.
The Reporting API allows REST-based access to data presented in OLAP CloudHealth Reports through this endpoint.
https://chapi.cloudhealthtech.com/olap_reports
Which Reports are Queryable
You can only retrieve data presented in OLAP reports. These are reports that are:
- available at the
/olap_reports
endpoint (including the Container Cost History report), and - present data visually through charts and graphs
Reporting Terminology
Familiarize yourself with the terminology specific to this API.
- Report name: The display name of the report (e.g., Instance Usage).
- Dimensions: Available members for the X-axis and categorization (e.g. by Days categorized by Reservation Type).
- Intervals: The granularity of the report (e.g., monthly, weekly, or hourly).
- Measures: Selected measures (e.g. # Instances).
- Filters: User-defined filters for the report.
- Data: The data that is returned when requesting a report.
See how these terms match to elements of the Report interface in the CloudHealth Platform.
Understand Report Data Format
Familiarize yourself with the format of the response that a Standard Report query returns.
When you query a Standard Report, the response you receive has the following general structure.
{
"report":"Instance Usage",
"dimensions":[
{
"time":[...]
},
{
"EC2-Reservation-Execution-Mode":[...]
}
],
"measures":[
{
"name":"usage_quantity",
"label":"# Instances"
}
],
"interval":"daily",
"filters":[...],
"updated_at":"2018-02-05T03:08:40+00:00",
"data":[
[[100, 40, 60], [60, 20, 40], [40, 20, 20], ...],
[...],
],
"status":"ok"
}
Let’s break down this response.
report
is a string that contains the display name of the report (e.g., Instance Usage).dimensions
is an array that contains the available members for the X-axis and categorization (e.g., by Days categorized by Reservation Type).measures
is an array that contains the selected measures for the report (e.g. # Instances)interval
is a string that contains the granularity of the report (e.g., monthly, weekly, or hourly)filters
is an array that contains all the filters selected for the reportdata
is an array that contains the report data
See how these fields match to elements of the Report interface in the CloudHealth Platform.
Among these fields, the data
field deserves some more explanation. The structure of this field depends on the structure and content of the dimensions
field.
Let’s say that the dimensions
field contains the following array.
"dimensions": [
{
"Past-12-Months": [
{"label": "Total", "name": "total"},
{"label": "2013-10", "name": "2013-10"},
{"label": "2013-11", "name": "2013-11"},
...
]
},
{
"AWS-Service-Category": [
{"label": "Total", "name": "total"},
{ "label": "EC2 - Compute", "name": "ec2_compute" },
{ "label": "EC2 - Transfer", "name": "ec2_transfer" },
...
]
}
]
Then the corresponding data
field might contain the following array.
"data": [
[[100, 40, 60], [60, 20, 40], [40, 20, 20], ...],
[[30, 20, 10], [20, 10, 10], [10, 0, nil], ...],
[[70, 40, 30], [40, 20, 20], [30, 20, 10], ...],
]
Each row in data
corresponds to time periods in the first subarray inside dimensions
.
Let’s only consider the first row in data
and correlate it with the structure of dimensions
.
[[100, 40, 60], [60, 20, 40], [40, 20, 20], ...]
Within this row is the data specific to the second subarray inside dimensions
, namely AWS-Service-Category
.
Putting it all together, each row in data
combines one or more dimensions.
If a cell contains 0
, there was data for the specified dimension member in the underlying data analyzed, but the aggregate total was 0
. If a cell contains null
, there was no data for this dimension member in the underlying data analyzed.
Understand Time Filters
Familiarize yourself with how time filters work when used with the Reporting API.
Filtering on the time dimension is a common technique for reducing the data returned from a report query. For example, you might want to get report data for last month, this quarter, or the previous year.
The time dimension is unique because it is ordinal. So one way to filter by this dimension is to provide an index value that indicates position. You can specify an Absolute Time Index (positive integers) or a Relative Time Index (negative integers).
Example: Get Data for Current Month
- Using Relative Time Index
&interval=monthly&filters[]=time:select:-1
- Using Absolute Time Index
&interval=monthly&filters[]=time:select:12
Example: Get Data for Past Three Months
- Using Relative Time Index
&interval=monthly&filters[]=time:select:-1,-2,-3
- Using Absolute Time Index
&interval=monthly&filters[]=time:select:12,11,10
If you are only select
-ing months (not weeks, days, or hours) and not reject
-ing months, you can specify the dimension as a date string instead of an index. The date string has the format YYYY-MM
. You can use this approach to filter out all months except for the current month.
&interval=monthly&filters[]=time:select:2014-12
You cannot mix and match date strings and indexes in a single filter.
Weekly, daily, and hourly (for reports that provide this interval) intervals work similarly. However, the amount of data retrieved for each interval is different.
Interval | Units | Relative Index |
---|---|---|
monthly |
12 months | -1 returns Current month |
weekly |
52 weeks | -1 returns the previous full week |
daily |
31 days | -1 returns the previous full day |
hourly |
84 hours | -1 returns from 10 PM to 11:59 PM UTC the day before (each member has two hours of data) |
Query Response Size Optimization
Multidimensional queries, by default, return a complete response across all the dimensions. Depending on the complexity of the report query, the result can return a much larger dataset. This dataset may include arrays containing only null values. To optimize the response to such queries, CloudHealth has introduced a new boolean parameter collapse_null_arrays
. If specified in the query, arrays with all the cost values as null would collapse to a single null value, thus significantly reducing the query response size. Consider the following example to understand how this parameter works.
Following is the example of a 3-D query over time/accounts/services, with slicing on time and AWS service categories.
curl -X GET -H 'Authorization: Bearer <Your API Key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/olap_reports/cost/history?\
interval=monthly&\
dimensions\[\]=AWS-Service-Category&\
dimensions\[\]=time&\
dimensions\[\]=AWS-Account&\
measures\[\]=cost&\
filters\[\]=time:select:-5,-1&\
filters\[\]=AWS-Service-Category:select:ec2_compute,nat_gateway_transfer,ec2_transfer,ebs_storage,nat_gateway_usage,ebs_io&\
NO_CACHE=1"
Note that the Data node in the query response may have multiple 2-D arrays with all cost values as null
, leading to an unnecessary increase in the data size to 345 KB.
"data": [
[
[
[
2936970.8662986687
],
[
2303183.584927046
],
[
440173.0578069503
],
[
26266.99529305149
],
[
61661.31648144288
],
[
77100.0010629067
],
[
null
],
[
19137.5030886411
],
[
2039.3415658562
],
[
null
],
[
null
],
[
null
],
[
null
],
[
7409.0660727718
]
],
[
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
],
[
null
]
],
...
]
]
Now, append the collapse_null_arrays
parameter to the same query.
curl -X GET -H 'Authorization: Bearer <Your API Key>' -H 'Content-Type: application/json' "https://chapi.cloudhealthtech.com/olap_reports/cost/history?\
interval=monthly&\
dimensions\[\]=AWS-Service-Category&\
dimensions\[\]=time&\
dimensions\[\]=AWS-Account&\
measures\[\]=cost&\
filters\[\]=time:select:-5,-1&\
filters\[\]=AWS-Service-Category:select:ec2_compute,nat_gateway_transfer,ec2_transfer,ebs_storage,nat_gateway_usage,ebs_io&\
NO_CACHE=1&\
collapse_null_arrays=1"
The query retrieves a simplified response as compared to the original query response by replacing the 2-D null arrays with a single null value.
"data": [
[
[
[
2936970.8662986687
],
[
2303183.584927046
],
[
440173.0578069503
],
[
26266.99529305149
],
[
61661.31648144288
],
[
77100.0010629067
],
[
null
],
[
19137.5030886411
],
[
2039.3415658562
],
[
null
],
[
null
],
[
null
],
[
null
],
[
7409.0660727718
]
],
null,
...
]
]
After adding the collapse_null_arrays
parameter, the resultant response size is 43 KB, much less than the original query response. The parameter only makes changes in the response format and returns the data that is useful to you.
NOTE:
- To process the new result set, you need to add a simple nil check to the logic.
- Since the response to 3D and 4D queries can be very large, verifying a small data set by appending the
collapse_null_arrays
parameter is recommended before submitting the larger requests.
List of Queryable Reports
Retrieve a list of Standard OLAP reports that you can query.
https://chapi.cloudhealthtech.com/olap_reports
Parameters
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
The response to this query contains a list of endpoints that provide Standard CloudHealth reports of specific types. The following endpoints are returned.
/cost
/custom
/performace
/usage
These endpoints are hierarchical. For example the /cost
endpoint branches out into specific reports of that type
Branch | Report name in CloudHealth Platform |
---|---|
history |
Cost History |
current |
Current Cost |
instance |
EC2 Instance Cost |
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports'
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' https://chapi.cloudhealthtech.com/olap_reports' | python -m json.tool
{
"links": {
"cost": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost"
},
"custom": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/custom"
},
"performance": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/performance"
},
"usage": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/usage"
}
}
}
List Reports of Specific Type
Retrieve the list of available Standard OLAP reports of a specify type.
https://chapi.cloudhealthtech.com/olap_reports/:report-type
Parameters
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
Retrieving a list of all reports of a specific type, such as /cost
, /custom
, /performance
, or /usage
is a two-step process.
-
Get the endpoints for all types of Standard reports.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports'
This query returns the following response.
{ "links": { "cost": { "href": "https://chapi.cloudhealthtech.com/olap_reports/cost" }, "custom": { "href": "https://chapi.cloudhealthtech.com/olap_reports/custom" }, "performance": { "href": "https://chapi.cloudhealthtech.com/olap_reports/performance" }, "usage": { "href": "https://chapi.cloudhealthtech.com/olap_reports/usage" } } }
-
Query the endpoint for the type of report from this response and get a list of all reports of that type.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/cost'
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports'
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/cost'`
{
"links": {
"amortized": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost/amortized"
},
"current": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost/current"
},
"history": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost/history"
},
"instance": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost/instance"
},
"rds": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost/rds"
},
"ri_amortization": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost/ri_amortization"
},
"s3": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost/s3"
},
"volume": {
"href": "https://chapi.cloudhealthtech.com/olap_reports/cost/volume"
}
}
}
Data for Standard Report
Retrieve the data for a specific Standard report.
https://chapi.cloudhealthtech.com/olap_reports/:report-type/:report-id
Parameters
-
dimensions
Array that specifies the members to use for Categorization and the X-Axis.
-
measures
Array that specifies the Y-axis measures to use for the report.
-
interval
String that specifies the granularity of report data.
-
filters
Array that specifies the filters to use for constraining report data.
Retrieving the data for a specific Standard report, such as /cost/history
, /cost/current
, or /usage/instance
involves the following steps.
-
Get the endpoints for all types of Standard reports.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports'
This query returns the following response.
{ "links": { "cost": { "href": "https://chapi.cloudhealthtech.com/olap_reports/cost" }, "custom": { "href": "https://chapi.cloudhealthtech.com/olap_reports/custom" }, "performance": { "href": "https://chapi.cloudhealthtech.com/olap_reports/performance" }, "usage": { "href": "https://chapi.cloudhealthtech.com/olap_reports/usage" } } }
-
Query the endpoint for the type of report from this response and get a list of all reports of that type. This example request queries the
/usage
endpoint to get a list of all Standard Usage Reports.curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage'
This query returns the following response, which has been truncated here for simplification.
Note: Only those reports that have
/olap_reports
in their endpoint are accessible through the API.{ "links":{ [...] "usage/instance":{ "href":"https://chapi.cloudhealthtech.com/olap_reports/usage/instance" }, "usage/volume":{ "href":"https://chapi.cloudhealthtech.com/olap_reports/volume" }, [...] } }
-
Query the endpoint for the specific report to get its data. This example request queries the
/usage/instance
endpoint to get the data for the EC2 Instance Usage report.curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance'
This query returns the following response, which has been truncated here for simplification.
{ "report":"Instance Usage", "dimensions":[ { "time":[...] }, { "EC2-Reservation-Execution-Mode":[...] } ], "measures":[ { "name":"usage_quantity", "label":"# Instances" } ], "interval":"daily", "filters":[...], "updated_at":"2018-02-05T03:08:40+00:00", "data":[ [[100, 40, 60], [60, 20, 40], [40, 20, 20], ...], [...], ], "status":"ok" }
Depending on which Standard Report you query, the response might vary in structure. However, all responses have common elements. See Understand Report Data Format.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance'`
{
"report":"Instance Usage",
"dimensions":[
{
"time":[...]
},
{
"EC2-Reservation-Execution-Mode":[...]
}
],
"measures":[
{
"name":"usage_quantity",
"label":"# Instances"
}
],
"interval":"daily",
"filters":[...],
"updated_at":"2018-02-05T03:08:40+00:00",
"data":[
[[100, 40, 60],
[60, 20, 40],
[40, 20, 20], ...],
[...],
],
"status":"ok"
}
Data for Custom Report
Retrieve the data for a custom Standard report.
https://chapi.cloudhealthtech.com/olap_reports/custom/:report-id
Parameters
-
dimensions
Array that specifies the members to use for Categorization and the X-Axis.
-
measures
Array that specifies the Y-axis measures to use for the report.
-
interval
String that specifies the granularity of report data.
-
filters
Array that specifies the filters to use for constraining report data.
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
Custom reports are saved versions of Standard Reports. Retrieving the data for a specific saved report involves the following steps.
-
Get the ID of the custom report.
In the CloudHealth Platform, from the left menu, click Reports > Saved Reports. Click the View Report icon next to the report you want to retrieve.
The URL in your browser contains the ID of the selected report.
-
Query the endpoint for the specific report to get its data.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/custom/<Report-ID>'
This query returns a response similar to this truncated one.
{ "report":"Cost History", "dimensions":[ { "time":[...] }, { "AWS-Service-Category":[...] } ], "measures":[ { "name":"cost", "label":"Cost ($)" } ], "interval":"weekly", "filters":[...], "updated_at":"2018-02-05T03:08:40+00:00", "data":[ [[100, 40, 60], [60, 20, 40], [40, 20, 20], ...], [...], ], "status":"ok" }
Depending on which saved report you query, the response might vary in structure. However, all responses have common elements. See Understand Report Data Format.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/custom/<Report-ID>'
{
"report":"Cost History",
"dimensions":[
{
"time":[...]
},
{
"AWS-Service-Category":[...]
}
],
"measures":[
{
"name":"cost",
"label":"Cost ($)"
}
],
"interval":"weekly",
"filters":[...],
"updated_at":"2018-02-05T03:08:40+00:00",
"data":[
[[100, 40, 60], [60, 20, 40], [40, 20, 20], ...],
[...],
],
"status":"ok"
}
Report Dimensions and Measures
Get dimensions and measures for a report so that you can build granular report queries
https://chapi.cloudhealthtech.com/olap_reports/:report-type/:report-id/new
Parameters
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
You can build granular report queries by passing dimensions and measures into the query string. In order to build detailed queries, first discover which dimensions and measures are available at the endpoint for each report.
Each report has a /new
endpoint that returns the dimensions and measures available for that report.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance/new'
{
"dimensions": [
{
"label": "Owner Perspective",
"name": "Groupset-998"
"members": [
{
"label": "Joe",
"name": "1392"
},
{
"label": "Sue",
"name": "1388"
},
{
"label": "No Owner Found",
"name": "1386"
}
],
},
{
"label": "Function Perspective",
"name": "Groupset-999"
"members": [
{
"label": "Zookeeper",
"name": "27715"
},
{
"label": "Databases",
"name": "27716"
},
...
],
},
{
"label": "Availability Zones",
"name": "AWS-Availaibility-Zones"
"members": [
{
"label": "us-east-1a",
"name": "us-east-1a"
},
{
"label": "us-east-1b",
"name": "us-east-1b"
},
{
"label": "us-east-1d",
"name": "us-east-1d"
}
],
},
{
"label": "Days",
"name": "time"
"members": [
{
"label": "2014-08-27",
"name": "1"
},
{
"label": "2014-08-28",
"name": "2"
},
...
],
}
...
],
"measures": [
{
"label": "# Instances",
"name": "usage_quantity"
},
{
"label": "Total Cost ($)",
"name": "cost"
},
{
"label": "Compute Cost ($)",
"name": "ec2_cost_compute"
},
{
"label": "Transfer Cost ($)",
"name": "ec2_cost_transfer"
},
{
"label": "# Reservations",
"name": "count"
},
{
"label": "On-Demand Cost ($)",
"name": "ec2_cost_on_demand"
},
{
"label": "# Instance Hours",
"name": "instance_hours"
}
]
}
Get Query for a Report
Retrieve the query string and parameters that produce a Standard or Custom OLAP report.
Parameters
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
Each CloudHealth report is produced by a combination of parameters that together compose a query string. You can retrieve the query string that produces a Standard or Custom report.
Because the response is JSON, meta characters are Unicode encoded.
curl -v -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/custom/{report-id}?get_query=true'
{
"query":"report=My Saved Report?dimensions[]=AWS-Account&dimensions[]=AWS-Service-Category&measures[]=cost&measures[]=cost_recurring&interval=monthly&filters[]=time:select:-1"
}
Add Dimensions and Measures to Report Query
Customize the granularity of report data by building complex queries that employ measures, dimensions, and filters. This example shows how to build a complex query to get the EC2 Compute Cost by Availability Zone for a monthly granularity.
-
Retrieve the list of available measures and dimensions of for the EC2 Instance Report.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' "https://chapi.cloudhealthtech.com/olap_reports/usage/instance/new"
This query returns a response that looks like this.
{ "dimensions": [ { "label": "Owner Perspective", "name": "Groupset-998" "members": [...], }, { "label": "Function Perspective", "name": "Groupset-999" "members": [...], }, { "label": "Availability Zones", "name": "AWS-Availability-Zones" "members": [ { "label": "us-east-1a", "name": "us-east-1a" }, ... ], }, { "label": "Days", "name": "time" "members": [ { "label": "2018-01-10", "name": "1" }, ... ], } ... ], "measures": [ { "label": "# Instances", "name": "usage_quantity" }, { "label": "Total Cost ($)", "name": "cost" }, { "label": "Compute Cost ($)", "name": "ec2_cost_compute" }, { "label": "Transfer Cost ($)", "name": "ec2_cost_transfer" }, { "label": "# Reservations", "name": "count" }, { "label": "On-Demand Cost ($)", "name": "ec2_cost_on_demand" }, { "label": "# Instance Hours", "name": "instance_hours" } ] }
-
Build a complex query that gets the EC2 Compute Cost by Availability Zone for a monthly granularity.
For each dimension, add a query parameter called
dimensions[]
and for each measure add a parameter calledmeasures[]
. For each of these parameters, specify one or more values that you received when querying the/new
endpoint. In general, the dimensions available arehourly
,daily
,weekly
, andmonthly
. You can add up to 4 dimensions.curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance? dimensions[]=time &dimensions[]=AWS-Availability-Zones &measures[]=ec2_cost_compute &interval=monthly'
Add Filters to Report Query
Use filters in conjunction with dimensions and measures to build complex queries.
Report filters help you reduce the data that is returned by a report query. You can use filters in conjunction with dimensions and measures to build complex queries.
For example, to get the EC2 Compute Cost in us-east-1a
, you can apply a filter in this way.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance?
dimensions\[\]=time
&dimensions\[\]=AWS-Availability-Zones
&measures\[\]=ec2_cost_compute
&filters\[\]=AWS-Availability-Zones:select:us-east-1a
&interval=monthly'
In the query, each filter is represented using the filters[]
parameter. this parameter has the this structure.
dimension-name:select|reject:member-name,member-name
The select
operator indicates which dimension members that you want to include and the reject
, the dimension members that you want to exclude.
For example, to get the EC2 Compute Costs for all Availability Zones except us-east-1b
and us-east-1d
, you can apply a filter in this way.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/usage/instance
?dimensions\[\]=time
&dimensions\[\]=AWS-Availability-Zones
&measures\[\]=ec2_cost_compute
&filters\[\]=AWS-Availability-Zones:reject:us-east-1b,us-east-1d
&interval=monthly'
For more information on how to filter by time, see Understand Time Filters.
Assets
Introduction to Assets API
An introduction to the Assets API.
The Assets API allows you to retrieve information on AWS, Azure, Data Center, and Google Cloud assets in your environment. The API supports the following operations:
- Retrieve the API names of all AWS, Azure, Data Center, and Google Cloud asset objects that you can query in the CloudHealth Platform.
- Retrieve the attributes of an asset, including the Perspective Groups to which the asset belongs, as well as assets related to the queried asset.
- Query objects of a specific type, filter objects by attribute, and list specific fields of assets in the response.
List of Queryable Assets
Retrieve the API names of all AWS, Azure, Data Center, and Google Cloud asset objects that you can query in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/api
Parameters
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
The response to this query contains a list of JSON objects that represent all the AWS, Azure, Data Center, and Google Cloud assets that CloudHealth has discovered in your environment.
curl -H 'Authorization: Bearer <your_api_key>' 'https://chapi.cloudhealthtech.com/api'
[
"AwsInstanceType",
...
"AwsCloudtrailTrail",
"AwsConfigRuleEvaluationResult",
"AwsConfigRule",
"AwsIamRole",
"AwsIamServerCertificate",
...
"IntegrationNode",
"IntegrationTag",
"JiraAccount",
"NewrelicAccount",
"GcpComputeInstance",
...
"AzureResourceGroup",
"AzureSearchService",
"AzureSqlDatabase",
"AzureSqlServer",
"AzureStorSimpleDeviceManager",
...
"AlertlogicAccount",
"DataCenterServerCpu",
"DataCenterTag",
"VmwareHost",
"VmwareVirtualMachine",
...
"AwsInstanceReservationListing",
"AwsInstanceReservationModificationItem",
"AwsInstanceReservationModification",
"AwsInstanceReservation",
...
]
Attributes of Single Asset
Retrieve the attributes and related assets for a single asset object.
https://chapi.cloudhealthtech.com/api/:asset
Parameters
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
The response to this query contains two arrays: attributes
and relations
.
The first array, attributes
, lists the primary attributes of the AWS, Azure, Data Center, or Google Cloud asset that you want to explore. For example, an AWS Instance has attributes such as Account ID, Instance ID, Public IP, and Private IP. The attributes
array also includes the Perspective Groups to which the AWS Instance belongs.
The relations
array contains related assets. In the case of an AWS Instance, the relations
array lists objects such as AwsAccount
, AWSInstanceType
, AwsAvailabilityZone
, and ChefNode
objects.
curl -H 'Authorization: Bearer <your_api_key>' 'https://chapi.cloudhealthtech.com/api/AwsInstance'
{
"name":"AwsInstance",
"attributes":[
{ "name":"id" },
{ "name":"instance_id" },
{ "name":"public_ip" },
...
{ "name":"usage_percentage_per_month" },
...
{
"name": "attr_group__XXXXX3562234",
"perspective_name": "Environment"
},
{
"name": "attr_group__XXXXX3562234",
"perspective_name": "Owner"
},
...
{
"name": "attr_group__XXXXX35623434",
"perspective_name": "Team"
}
],
"relations":[
{
"name": "account",
"object_type": "AwsAccount",
"has_many": false
},
{
"name": "instance_type",
"object_type": "AwsInstanceType",
"has_many": false
},
...
{
"name": "auto_scaling_group",
"object_type": "AwsAutoScalingGroup",
"has_many": false
},
...
]
Search for Assets
Build a search query that retrieves assets that match specific criteria.
https://chapi.cloudhealthtech.com/api/search
Parameters
-
namerequired
String that specifies the type asset object to query, for example, AWSInstance, AzurePolicyAssignment, or AzurePolicyStates.
-
queryrequired
Criteria for finding assets of a particular asset object type. Enclose query parameter values in single quotes. This also applies to boolean assignment values that are either
True
orFalse
. Format isquery='[field value]'[operator][value]
. For example,query=name='MyAccount'+and+is_private=0
. -
include
String that specifies the name of a related asset object to include when returning a response. You cannot use both the
include
parameter and thefields
parameter in the same GET query. -
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
-
api_version
Integer that specifies the API version to use. Possible values are
1
(default) and2
. Version 1 queries only return assets that are active. Version 2 queries return both active and inactive assets.-
fields
Only available when
api_version=2
. Comma-separated list that specifies the specific fields to return when querying the asset object. -
page
Only available when
api_version=2
. Integer that specifies the page to display when results run over multiple pages. Default value is1
. If this parameter is missing, the query returns all results, even if theper_page
parameter is specified. -
per_page
Only available when
api_version=2
. Integer that specifies the number of assets to return per page. Default value is100
and maximum value is1000
. -
query
Only available when
api_version=2
. Filter query results based on one or more field values. For example, return only active assets by setting this parameter tois_active=1
.
-
See Asset Query Examples.
curl -H 'Authorization: Bearer <your_api_key>' 'https://chapi.cloudhealthtech.com/api/search?
&api_version=2
&page=1
&per_page=5
&name=AwsVolume
&query=is_active=1
&fields=in_use,attr_group__XXXXX,account.name
[
{
"in_use": true,
"attr_group__XXXXXXYY": "Other",
"account": {
"name": "Primary Account",
"id": 90
},
"id": XXXXXXYY
},
{
"in_use": false,
"attr_group__XXXXXXYY": "Other",
"account": {
"name": "Staging Account",
"id": 90
},
"id": XXXXXXYYZZ
},
...
{
"in_use": true,
"attr_group__XXXXXXYY": "Other",
"account": {
"name": "Testing Account",
"id": 1511828488197
},
"id": XXXXXXYYDD
}
]
Asset Query Examples
Multiple examples that demonstrate how you can use the Asset API.
List API names for all asset types
curl -H 'Authorization: Bearer <your_api_key>'
"https://chapi.cloudhealthtech.com/api"
List available fields for AWS RDS Instances
curl -H 'Authorization: Bearer <your_api_key>'
"https://chapi.cloudhealthtech.com/api/AwsRdsInstance"
List available fields for Azure Virtual Machines
curl -H 'Authorization: Bearer <your_api_key>'
"https://chapi.cloudhealthtech.com/api/AzureVm"
List available fields for AWS Load Balancer
curl -H 'Authorization: Bearer <your_api_key>'
"https://chapi.cloudhealthtech.com/api/AwsLoadBalancer"
Filter AWS Load Balancers by name
curl -H 'Authorization: Bearer <your_api_key>' "https://chapi.cloudhealthtech.com/api/search?
&name=AwsLoadBalancer
&query=name='a45075XXXXXXYYYYYYZZZZZ96f99'"
Filter RDS Instances by instance ID and only display the instance IDs in the response
curl -H 'Authorization: Bearer <your_api_key>' "https://chapi.cloudhealthtech.com/api/search?
&name=AwsRdsInstance
&api_version=2
&fields=instance_id
&instance_id=<instance_id>"
List active AWS Volumes and only display their Perspective Groups and Accounts in the response
curl -H 'Authorization: Bearer <your_api_key>' https://chapi.cloudhealthtech.com/api/search?
&api_version=2
&page=1
&per_page=5
&query=is_active=1
&name=AwsVolume
&fields=in_use,attr_group__33XXSSDDYYYY,account.name
Include only instance as related object when searching for AWS Volumes
curl -H 'Authorization: Bearer <your_api_key>' 'https://chapi.cloudhealthtech.com/api/search?
&api_version=2
&page=1
&per_page=5
&name=AwsVolume
&include=instance
Metrics
Introduction to Metrics API
An introduction to the Metrics API and its limitations.
The Metrics API allows REST-based access to performance metrics, such as CPU, Memory, and Disk for AWS assets.
The Metrics API allows you to read and write various performance metrics at this endpoint.
https://chapi.cloudhealthtech.com/metrics/v1
Once you have uploaded metrics, you have improved insight into the health and performance of your cloud environment. In addition, the CloudHealth Platform is able to generate better rightsizing recommendations based on these metrics.
Limitations
- You can only post CPU, memory, and file system metrics.
- You can only post up to 8 days of historical metrics data.
- Metrics must have an hourly resolution.
- An active AWS Instance associated with the metrics must already be present and active in the CloudHealth Platform and not be Chef-managed.
- Metric retrieval is for individual assets only, that is, for AWS EC2 Instances or file systems of AWS EC2 Instances.
- The payload can contain a max of 1000 data points. If there are more than 1000 data points, the entire request is rejected with a
422
response. - When posting to file systems, the associated instance must be present and active. However, if a file system object does not currently exist, a new one is automatically created and linked to the instance.
Rate Limits
Understand rate limits when making requests to the Metrics API.
CloudHealth limits the rate at the user, namely API key, level.
- A total of 60 POST requests are allowed per minute.
- Read requests are not throttled.
- A
429
HTTP status code is returned if the request is throttled. The client should be written to handle this response and retry with an exponential backoff. - Since a payload can contain up to 1000 data points, a single client can push 60,000 data points per minute.
Understand Format of Metrics Payload
Learn how to format the payload for uploading metric to the CloudHealth Platform.
Familiarize yourself with the format of the payload that you can post through the Metrics API.
You can send metrics as a collection of datasets. Each dataset describes a single asset type, either instance or file system and consists of these components.
- a metadata header describing the data being sent
- an array of values that represent the actual metrics data
One or more datasets are bound up in a hash rooted with the metrics element.
"metrics": {
"datasets": []
}
Here’s an example of the payload.
{
"metrics": {
"datasets": [
{
"metadata": {
"assetType": "aws:ec2:instance",
"granularity": "hour",
"keys": [
"assetId",
"timestamp",
"memory:free:bytes.avg",
"memory:free:bytes.max",
"memory:free:bytes.min"
"memory:size:bytes.avg",
"memory:size:bytes.max",
"memory:size:bytes.min"
"memory:used:percent.avg",
"memory:used:percent.max",
"memory:used:percent.min"
]
},
"values": [
[
"us-east-1:12345678:i-99999999",
"2015-06-03T01:00:00+00:00",
53687391300,
107374182400,
26843545600,
322122547200,
322122547200,
322122547200,
16.67,
33.33,
8.33
],
[
"us-east-1:12345678:i-88888888",
"2015-06-03T02:00:00+00:00",
53687391300,
107374182400,
26843545600,
322122547200,
322122547200,
322122547200,
16.67,
33.33,
8.33
]
]
}
]
}
}
Let’s take a look at the metadata array, which describes the data you are sending. It consists of these components:
- an asset type
- the granularity of the included data
- an array of keys that describes the
type
of each element in the values array
"metadata": {
"assetType": 'aws:ec2:instance',
"granularity": 'hour',
"keys" [
"assetId",
"timestamp",
"memory:free:bytes.avg",
"memory:free:bytes.max",
...
]
}
The metadata array contains the assetType
, granularity
, and keys
fields, which can take specific values.
Field: assetType
Supported Values | keys Field |
---|---|
aws:ec2:instance |
cpu:used:percent.avg |
cpu:used:percent.min |
|
cpu:used:percent.max |
|
memory:free:bytes.avg |
|
memory:free:bytes.min |
|
memory:free:bytes.max |
|
memory:size:bytes.avg |
|
memory:size:bytes.min |
|
memory:size:bytes.max |
|
memory:used:percent.avg |
|
memory:used:percent.min |
|
memory:used:percent.max |
|
assetId |
|
timestamp |
|
aws:ec2:instance:fs |
fs:size:bytes.avg |
fs:size:bytes.min |
|
fs:size:bytes.max |
|
fs:used:bytes.avg |
|
fs:used:bytes.min |
|
fs:used:bytes.max |
|
assetId |
|
timestamp |
Field: granularity
Supported Values: hour
The values array has an entry for each series of metrics you want to post. Each entry is itself an array of metrics corresponding to the elements in the keys
array, that is, in the same order and of the same length.
Each entry array consists of these components.
- Instance specification using a compact form of the AWS ARN format (
<region>:<account-number>:<AWS-instance-ID>
) or file system specification using a compact form of the AWS ARN format (<region>:<account-number>:<AWS-instance-ID>:<file-system-mount-point>
) - UTC-based timestamp that is on the hourly boundary specified in ISO-8601 format
An entry for instance might look like this.
"values": [
[ "us-east-1:12345678:i-a99a99a9", "2015-06-03T00:01:00+00:00", 200, 400, ...],
[ "us-east-1:12345678:i-a99a99a9", "2015-06-03T00:02:00+00:00", 100, 300, ...],
]
While an entry for a file system might look like this.
"values": [
[ "us-east-1:12345678:i-a99a99a9:/opt", "2015-06-03T00:01:00+00:00", 200, 400, ...],
[ "us-east-1:12345678:i-a99a99a9:/opt", "2015-06-03T00:02:00+00:00", 100, 300, ...],
]
Once you build the payload, you can use a cURL command to post it to the /metrics/v1
endpoint.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/metrics/v1" -d '{"metrics":{"datasets":[{"metadata":{"assetType":"aws:ec2:instance","granularity":"hour","keys":["assetId","timestamp","memory:usedPercent.avg","memory:usedPercent.max","memory:usedPercent.min"]},"values":[["us-east-1:12345678:i-99999999","2015-06-03T01:00:00+00:00",100.0,200.0,50.0],["us-east-1:12345678:i-88888888","2015-06-03T02:00:00+00:00",25.5,45.2,15.0]]}]}}'
Metrics for Single Asset
Retrieve CPU, memory, and performance metrics for a specific asset
https://chapi.cloudhealthtech.com/metrics/v1
Parameters
-
assetrequired
String that specifies the AWS ARN that identifies the asset. The format is
arn:aws:ec2:<region>:<owner-id>:instance/<AWS-instance-ID>
. For example,arn:aws:ec2:us-east-1:123456789012:instance/i-01a1234b56cdef7g8
. -
granularity
String that specifies the resolution at which data should be returned. Possible values are
hour
(default),day
,week
, andmonth
. -
from
Date in
YYYY-MM-DD
format that specifies the start date from which you want to see metrics for the asset. You can use this parameter in conjunction with theto
parameter to specify a custom date range for metrics retrieval. -
to
Date in
YYYY-MM-DD
format that specifies the end date up to which you want to see metrics for the asset. You can use this parameter in conjunction with thefrom
parameter to specify a custom date range for metrics retrieval. -
time_range
String that specifies the time range limit to use when returning data. Possible values are
yesterday
(default),mtd
,last_month
,last_3_months
,last_6_months
,last_12_months
,wtd
,last_week
,last_2_weeks
,last_4_weeks
,last_52_weeks
,today
,yesterday
,last_2_days
,last_7_days
,last_14_days
, andlast_31_days
-
page
Integer that specifies the page to display when results run over multiple pages. Default value is
1
. If this parameter is missing, the query returns all results, even if theper_page
parameter is specified. -
per_page
Integer between
1
and500
that specifies the number of assets to return per page. Default value is100
and maximum value is1000
. -
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
By default, the request returns hourly sets of metric points for the previous day. If there are more than 100 data value sets, a next link to the next page of value sets is also returned
The response format is not wrapped in the metrics
object. The response also contains a next
link that can be followed to retrieve the next 100 metrics. The next
attribute is null
if there are no more records to retrieve.
time_range
and granularity
Considerations
Ensure that the value of the time_range
parameter is large enough to encompass the requested granularity
. For example, asking for yesterday
’s data at a monthly
resolution returns no rows, not an error. Requesting yesterday
’s data with a granularity of day
returns one row.
In addition, rollups are calculated daily. You will not receive today
’s data at any granularity
other than hourly
, which is the default value.
curl 'https://chapi.cloudhealthtech.com/metrics/v1/?
&asset=arn:aws:ec2:<region>:<owner-id>:instance/<AWS-instance-ID>'
-H 'Authorization: Bearer <your_api_key>'
{
"datasets": [
"metadata" : {
"assetType" : "aws:ec2:instance",
"granularity" : "hour",
"keys" : [
"assetId",
"timestamp",
"cpu:used:percent.avg",
"cpu:used:percent.max",
"cpu:used:percent.min",
"memory:free:bytes.avg",
"memory:free:bytes.max",
"memory:free:bytes.min",
"memory:used:percent.avg",
"memory:used:percent.max",
"memory:used:percent.min"
]
},
"values" : [
[ "us-east-1:12345678:i-99999999", "2017-10-22T05:00:00Z", 76, 99, 51, null, null, null, 22.5, 52.2, 18.1 ],
[ "us-east-1:12345678:i-99999999", "2017-10-22T06:00:00Z", 91, 99, 81, null, null, null, 25.2, 53, 19.7 ]
]
]
}
Upload Metrics for Single Asset
Post metrics for an individual asset, including historical metrics data.
https://chapi.cloudhealthtech.com/metrics/v1
Parameters
-
JSON documentrequired
Payload containing the metrics that you want to post. See Understand Format of Metrics Payload.
-
dryrun
Test a POST operation without triggering a database change. Specified as
true
orfalse
(default). -
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
You can only post up to 8 days of historical metrics data.
The format of the response payload is similar to this one.
"succeeded": <The total number of rows that were successfully processed.>,
"failed": <The total number of rows that were rejected.>,
"errors": [
"<A textual description of all errors that prevented the entire payload or an entire dataset from being processed.>"
]
# Datasets provide details of failures at the row level within each dataset.
"datasets": [
{
"succeeded": <Count of all rows in this dataset that were successfully added to the system.>,
"errors": [
"<Textual representation of any errors that prevented all data in this dataset from being processed.>"
],
"failures": [
{
"error": "<Textual representation of any parsing errors that prevented a single row of data from being accepted.>"
"row:" <The original row data that was passed in>
}
]
}
Response code | Meaning |
---|---|
200 | Success / Partial failure |
400 | No data was processed. Possibly malformed JSON document. |
429 | Request was throttled |
500 | Error with CloudHealth servers. Do not resend request immediately. |
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -XPOST "https://chapi.cloudhealthtech.com/metrics/v1" -d '{"metrics":{"datasets":[{"metadata":{"assetType":"aws:ec2:instance","granularity":"hour","keys":["assetId","timestamp","memory:usedPercent.avg","memory:usedPercent.max","memory:usedPercent.min"]},"values":[["us-east-1:12345678:i-99999999","2015-06-03T01:00:00+00:00",100.0,200.0,50.0],["us-east-1:12345678:i-88888888","2015-06-03T02:00:00+00:00",25.5,45.2,15.0]]}]}}'
{
succeeded: 198,
failed: 2,
errors: 0,
datasets: [
{
"succeeeded": 100,
"errors": [],
"failures": []
},
{
"succeeeded": 98,
"errors": [],
"failures": [
{
"error": "Number of values (6) must equal number of keys (5).",
"row": [
"us-east-1:12345678:i-99999999",
"2015-06-03T02:00:00+00:00",
100,
75,
50,
111
]
},
{
"error": "Percentage value (101) is greater than 100.",
"row": [
"us-east-1:12345678:i-88888888",
"2015-06-03T03:00:00+00:00",
101,
75,
50
]
},
]
},
]
}
Tagging
Introduction to Tagging API
An introduction to the Tagging API and its limitations.
The Tagging API allows you to add tags (key-value pairs) to objects in the CloudHealth Platform, including taggable AWS assets, AWS accounts, taggable Azure assets, taggable GCP assets, and Data Center servers. These tags are completely independent of your cloud provider tags.
When you tag objects using this API, the resources are only tagged in the CloudHealth Platform. The tags do not cascade down to your cloud provider (AWS, Azure, GCP, or Data Center). CloudHealth continues to pull tags from both your cloud provider.
The Tagging API allows you to add tags at this endpoint.
https://chapi.cloudhealthtech.com/v1/custom_tags
Limitations
- No more than 100 instances per request
- No more than 100 tags per instance
- Tag keys must be between 1 and 127 characters long
- Tag values must be no longer than 255 characters long
- Tag values must be scalar. Lists and objects are not allowed. Numbers will be converted to strings.
- Tag value will be stripped of leading and trailing whitespace
How Tags are Processed
Understand the process through which CloudHealth updates tags.
You can use the Tagging API to add new tags as well update existing ones. For either operation, you pass a tagging payload with the API request. Here is an example of the payload structure.
{
"tag_groups": [
{
"asset_type": "AwsAccount",
"ids": [12345, 56789],
"tags": [{"key": "owner", "value": "Fred"}]
},
{
"asset_type": "AwsInstance",
"ids": [1511831925873],
"tags": [{"key": "environment", "value": "Test"}, {"key": "owner", "value": "Mary"}]
},
{
"asset_type": "AwsRdsInstance",
"ids": [206158446754],
"tags": [{"key": "environment", "value": "Production"}, {"key": "owner", "value": "Mary"}]
}
]
}
asset_type
is an asset that you can tag in the CloudHealth Platform.ids
is a list of CloudHealth IDstags
is a list of key-value tag pairs
CloudHealth runs through the following process when it receives the payload. The entire payload is processed. If failures occur, they are identified and processing continues.
Update Tags for Single Asset
Add, remove, or update tags that are associated with an asset.
https://chapi.cloudhealthtech.com/v1/custom_tags
Parameters
-
JSON documentrequired
Payload containing the tags that you want to post. See How Tags are Processed.
The response to the post request is JSON.
- Each successful update is shown to the
updates
array in the response. - Each partial failure is returned with an indication of which object or tag failed. Where possible, a descriptive message is also provided.
- If there is a mix of updates and errors, the HTTP response code will still be
200 OK
.
curl -H 'Authorization: Bearer <your_api_key>' -H "Accept: application/json" -H 'Content-Type: application/json' -XPOST 'https://chapi.cloudhealthtech.com/v1/custom_tags'
-d '{
"tag_groups":[
{
"asset_type": "AwsAccount",
"ids": [90],
"tags": [
{
"key": "testtag1",
"value": null
}
]
}
]
}'
{
"updates": [
{
"asset_type": "AwsAccount",
"asset_id": 12345,
"tag_key": "owner",
"tag_value": "Fred"
},
{
"asset_type": "AwsAccount",
"asset_id": 56789,
"tag_key": "owner",
"tag_value": "Fred"
},
{
...
}
],
"errors": [
{
"message": "Asset does not exist or user does not have access",
"asset_type": "AwsRdsInstance",
"asset_id": 206158446754
}
]
}
Organization
Introduction to Organization API
An introduction to the Organization API.
Organizations allow customers to limit the visibility of the data available to users in the CloudHealth Console. Using organizations, you can grant multiple stakeholders access to CloudHealth without providing them access to data you do not wish them to see (e.g. the marketing department should see only the infrastructure running on behalf of marketing).
To create an organization, you associate it with one or more accounts containing the data you want visible. Classic organizations may have overlapping data (e.g. both your Engineering and DevOps organizations might have access to a common set of accounts). FlexOrg organizations can be associated only with accounts belonging to their parent organizations.
By default, every company has one default organization that contains all accounts and their corresponding assets. You can modify and assign accounts to the default organization only through the CloudHealth Platform.
For more information on organizations, see the Organizations, Users, and Roles topic.
The Organization API allows admin users to create, modify, and delete organizations and assign AWS, Azure, GCP, and Data Center accounts to organizations. Users can assign Chef and Datadog accounts to an organization only through the CloudHealth Platform. In order to use some Organization endpoints, you need to provide the org_id
. CloudHealth generates a unique ID for each organization. See How to Get Organization ID.
Organization API is available in two versions. Version 2 is documented in the endpoints below. To access documentation for Version 1 (Legacy) API, contact support@cloudhealthtech.com.
How to Get Organization ID
In order to use some Organization endpoints, you need to provide the org_id
. CloudHealth generates a unique ID for each organization. You can get the Organization ID for an organization from the CloudHealth Platform. From the left menu, go to Setup > Admin > Organizations and view or edit the organization. The Organization ID appears in the browser URL. Here’s an example URL:
https://apps.cloudhealthtech.com/organizations/20XXXXXXXX09
Here, 20XXXXXXXX09
is the Organization ID.
The Organization ID can also be retrieved using the Get All Organizations endpoint.
Rate Limits
Understand rate limits when making requests to the Organization API.
CloudHealth limits the rate at the user, namely API key, level.
- A total of 500 requests are allowed every ten minutes for the following endpoints:
Create Organization
Add a new organization to the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v2/organizations
Parameters
-
namerequired
String that specifies the unique name of the new organization.
-
description
String that specifies a description of the organization.
-
parent_organization_id
String that specifies the ID of the parent organization. Applies only for organizations in FlexOrgs.
{
"name": "abc",
"description": "abc desc",
"parent_organization_id": "24"
}
{
"id":"6116033432624",
"parent_organization_id": "24",
"name": "abc",
"description": "abc desc",
"idp_name": "abc",
"flex_org": false,
"default_organization": true,
"assigned_users_count": 124,
"num_aws_accounts": 118,
"num_azure_subscriptions": 25,
"num_gcp_compute_projects": 15,
"num_data_center_accounts": 84,
"num_vmware_csp_organizations": 1
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name": "abc",
"description": "abc desc",
"parent_organization_id": "24"
}'
'https://chapi.cloudhealthtech.com/v2/organizations'
Get All Organizations
Retrieve a list of all organizations, including the number of accounts assigned to them.
https://chapi.cloudhealthtech.com/v2/organizations
Parameters
-
per_page
Specify how many results should be displayed per page. Default value is 30. Maximum value is 100.
-
page
Specify the page number for results.
-
org_id
String that specifies the ID of the organization in which this query should run. See How to Get Organization ID. If not specified, this parameter assumes the ID of your default organization.
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v2/organizations'
Modify Existing Organization
Modify an existing organization that already exists in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v2/organizations/:org_id
Parameters
-
name
String that specifies the unique name of the organization.
-
description
String that specifies a description of the organization.
{
"description": "abc 123"
}
{
"id":"6116033432624",
"name": "abc",
"description": "abc 123",
"idp_name": "abc",
"flex_org": false,
"default_organization": true,
"assigned_users_count": 124,
"num_aws_accounts": 118,
"num_azure_subscriptions": 25,
"num_gcp_compute_projects": 15,
"num_data_center_accounts": 84,
"num_vmware_csp_organizations": 1
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"description": "abc 123"
}'
'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>'
Delete Existing Organization
Delete an organization from the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v2/organizations/:org_id
curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>'
Assign Account to Organization
Assign accounts to an organization. If your organization is in FlexOrgs, run the Get All Allowed Accounts endpoint first to verify which accounts you can assign to the organization. Existing account assignments in the organization will be entirely replaced by the assignments you specify in the body of this request. If you want to add to existing account assignments, see Add Accounts to Existing Organization Account Assignment.
https://chapi.cloudhealthtech.com/v2/organizations/:org_id
Parameters
-
aws_accounts
Enter a comma-separated list of AWS account IDs (also known as the owner ID) that should be assigned to the organization. The account IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 AWS accounts per endpoint.
-
azure_subscriptions
Enter a comma-separated list of Azure subscription GUIDs that should be assigned to the organization. The subscription GUIDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 Azure accounts per endpoint.
-
gcp_compute_projects
Enter a comma-separated list of GCP project IDs that should be assigned to the organization. The project IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 GCP projects per endpoint.
-
data_center_accounts
Enter a comma-separated list of Data Center account names that should be assigned to the organization. The account names can be retrieved using the Search for Assets endpoint. You can assign up to 500 Data Center accounts per endpoint.
{
"aws_accounts":["12345","67890"],
"azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
"gcp_compute_projects":["gcp-project-name","gcp-new-project"],
"data_center_accounts":["myplace-datacenter"]
}
[{
"id":"6116033432624",
"name": "abc",
"description": "abc 123",
"idp_name": "abc",
"flex_org": false,
"default_organization": true,
"assigned_users_count": 124,
"num_aws_accounts": 118,
"num_azure_subscriptions": 25,
"num_gcp_compute_projects": 15,
"num_data_center_accounts": 84,
"num_vmware_csp_organizations": 1
}]
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"accounts":"add",
"aws_accounts":["12345","67890"],
"azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
"gcp_compute_projects":["gcp-project-name","gcp-new-project"],
"data_center_accounts":["myplace-datacenter"]
}'
'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>'
Add Accounts to Existing Organization Account Assignment
Add one of more accounts to an organization.
https://chapi.cloudhealthtech.com/v2/organizations/:org_id/accounts
Parameters
-
accountsrequired
Enter
add
to append accounts to the organization. -
aws_accounts
Enter a comma-separated list of AWS account IDs (also known as the owner ID) that should be assigned to the organization. The account IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 AWS accounts per endpoint.
-
azure_subscriptions
Enter a comma-separated list of Azure subscription GUIDs that should be assigned to the organization. The subscription GUIDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 Azure accounts per endpoint.
-
gcp_compute_projects
Enter a comma-separated list of GCP project IDs that should be assigned to the organization. The project IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 GCP projects per endpoint.
-
data_center_accounts
Enter a comma-separated list of Data Center account names that should be assigned to the organization. The account names can be retrieved using the Search for Assets endpoint. You can assign up to 500 Data Center accounts per endpoint.
{
"accounts":"add",
"aws_accounts":["12345","67890"],
"azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
"gcp_compute_projects":["gcp-project-name","gcp-new-project"],
"data_center_accounts":["myplace-datacenter"]
}
[{
"id":"6116033432624",
"name": "abc",
"description": "abc 123",
"idp_name": "abc",
"flex_org": false,
"default_organization": true,
"assigned_users_count": 124,
"num_aws_accounts": 118,
"num_azure_subscriptions": 25,
"num_gcp_compute_projects": 15,
"num_data_center_accounts": 84,
"num_vmware_csp_organizations": 1
}]
curl --request PATCH -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"accounts":"add",
"aws_accounts":["12345","67890"],
"azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
"gcp_compute_projects":["gcp-project-name","gcp-new-project"],
"data_center_accounts":["myplace-datacenter"]
}'
'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/accounts'
Get Organization Account Assignment
Retrieve a list of all accounts assigned to an organization.
https://chapi.cloudhealthtech.com/v2/organizations/:org_id/:cloud_account
Parameters
-
cloud_accountrequired
Specify the cloud account as
aws_accounts
for AWS,azure_subscriptions
for Azure,gcp_compute_projects
for GCP,data_center_accounts
for Data Center, orvmware_csp_organizations
for VMware Cloud. -
page
Specify the page number for results.
-
per_page
Specify how many results should be displayed per page. Default value is 30. Maximum value is 100.
-
query
Specify a keyword to filter accounts by. For example, specify
Production
to filter accounts by field and tag for the keyword Production. -
sort
Specify an attribute to sort accounts by. For example, specify
amazon_name
to sort accounts by the Amazon Name attribute. -
is_down
Boolean field that specifies whether accounts should be sorted in ascending or descending order. Specify
true
to sort accounts in descending order andfalse
to sort accounts in ascending order. Default value isfalse
.
{
"accounts": [
{
"name": "Example Subscription",
"region": "global",
"created_at": "2017-10-19T17:36:10Z",
"updated_at": "2019-04-03T04:49:49Z",
"account_type": "Unknown",
"status": "Critical",
"authentication_type": "Role Based",
"tags": []
},
{
"name": "Production Account",
"region": "global",
"created_at": "2018-05-02T05:51:20Z",
"updated_at": "2018-05-04T16:36:55Z",
"account_type": "Unknown",
"status": "Critical",
"authentication_type": "User Based",
"tags": [
{
"key": "Environment",
"value": "Production"
}
]
}
],
"_links": {
"next": {
"href": "/v2/organizations/:org_id/aws_accounts?page=2&per_page=30"
}
}
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/<cloud_account>'
Get All Allowed Accounts
Used in FlexOrgs only. Retrieves a list of accounts that belong to an organization and can be assigned to potential child organizations. Make a GET request to the parent organization of the organization you want to add accounts to.
https://chapi.cloudhealthtech.com/v2/organizations/:org_id/available_accounts
Parameters
-
typerequired
Specify the cloud account type as
aws_accounts
for AWS,azure_subscriptions
for Azure,gcp_compute_projects
for GCP,data_center_accounts
for Data Center, orvmware_csp_organizations
for VMware Cloud.
{
"aws_accounts": [
{
"id": "656265534892",
"name": "CloudHealth NG Dev",
"owner_id": "foo",
"account_type": "standalone",
"authentication_type": "role",
"status": "healthy",
"tags": { "foo": "bar", "baz": "bang" }
}
]
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/available_accounts?type=aws_accounts'
Replace Existing Organization Account Assignment
Replace an organization’s current account assignments with a new list of accounts. This endpoint removes all accounts currently assigned to the organization and replaces them with the new accounts.
https://chapi.cloudhealthtech.com/v2/organizations/:org_id/accounts
Parameters
-
aws_accounts
Enter a comma-separated list of AWS account IDs (also known as the owner ID) that should be assigned to the organization. The account IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 AWS accounts per endpoint.
-
azure_subscriptions
Enter a comma-separated list of Azure subscription GUIDs that should be assigned to the organization. The subscription GUIDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 Azure accounts per endpoint.
-
gcp_compute_projects
Enter a comma-separated list of GCP project IDs that should be assigned to the organization. The project IDs can be retrieved using the Search for Assets endpoint. You can assign up to 500 GCP projects per endpoint.
-
data_center_accounts
Enter a comma-separated list of Data Center account names that should be assigned to the organization. The account names can be retrieved using the Search for Assets endpoint. You can assign up to 500 Data Center accounts per endpoint.
{
"aws_accounts":["12345","67890"],
"azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
"gcp_compute_projects":["gcp-project-name","gcp-new-project"],
"data_center_accounts":["myplace-datacenter"]
}
[{
"id":"6116033432624",
"name": "abc",
"description": "abc 123",
"idp_name": "abc",
"flex_org": false,
"default_organization": true,
"assigned_users_count": 124,
"num_aws_accounts": 118,
"num_azure_subscriptions": 25,
"num_gcp_compute_projects": 15,
"num_data_center_accounts": 84,
"num_vmware_csp_organizations": 1
}]
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"aws_accounts":["12345","67890"],
"azure_subscriptions":["151f9055-7a93-4bbb","700f3a5c-8c56-44b9"],
"gcp_compute_projects":["gcp-project-name","gcp-new-project"],
"data_center_accounts":["myplace-datacenter"]
}'
'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/accounts>'
Delete Existing Organization Account Assignment
Remove one of more accounts from an organization.
https://chapi.cloudhealthtech.com/v2/organizations/:org_id/accounts
Parameters
-
accountsrequired
Enter
remove
to remove accounts assigned to the organization. -
aws_accounts
Enter a comma-separated list of AWS account IDs (also known as the owner ID) that should be removed from the organization. The account IDs can be retrieved using the Search for Assets endpoint. You can remove up to 500 AWS accounts per endpoint.
-
azure_subscriptions
Enter a comma-separated list of Azure subscription GUIDs that should be removed from the organization. The subscription GUIDs can be retrieved using the Search for Assets endpoint. You can remove up to 500 Azure accounts per endpoint.
-
gcp_compute_projects
Enter a comma-separated list of GCP project IDs that should be removed from the organization. The project IDs can be retrieved using the Search for Assets endpoint. You can remove up to 500 GCP projects per endpoint.
-
data_center_accounts
Enter a comma-separated list of Data Center account names that should be removed from the organization. The account names can be retrieved using the Search for Assets endpoint. You can remove up to 500 Data Center accounts per endpoint.
{
"accounts":"remove",
"aws_accounts":["12345"],
"azure_subscriptions":["151f9055-7a93-4bbb"],
"gcp_compute_projects":["gcp-project-name"],
"data_center_accounts":["myplace-datacenter"]
}
{
"id":"6116033432624",
"name": "abc",
"description": "abc 123",
"idp_name": "abc",
"flex_org": false,
"default_organization": true,
"assigned_users_count": 124,
"num_aws_accounts": 118,
"num_azure_subscriptions": 25,
"num_gcp_compute_projects": 15,
"num_data_center_accounts": 84,
"num_vmware_csp_organizations": 1
}
curl --request PATCH -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"accounts":"remove",
"aws_accounts":["12345"],
"azure_subscriptions":["151f9055-7a93-4bbb"],
"gcp_compute_projects":["gcp-project-name"],
"data_center_accounts":["myplace-datacenter"]
}'
'https://chapi.cloudhealthtech.com/v2/organizations/<org_id>/accounts'
Policies
Introduction to Policy API
An introduction to the Policy API.
The Policy API allows you to retrieve policy information and results. The API supports the following operations:
- Retrieve policy, policy block, and policy violation data for your policies in the CloudHealth Platform.
- For Partners, retrieve policy, policy block, and policy violation data for your partner customers’ policies in the CloudHealth Platform. Limited to policies in the partner customer’s default organization.
Get All Policies
Retrieve a list of all policies in your organization or in the specified partner customer’s default organization.
https://chapi.cloudhealthtech.com/v1/policies
Parameters
-
api_key
String that specifies the unique customer API Key, or Client API ID, that CloudHealth generates. Use this parameter if you are a partner who wants to retrieve a list of all policies belonging to a partner customer. See How to Get Client API ID.
-
per_page
Specify how many results should be displayed per page. Default value is 30.
-
page
Specify the page number for results.
Response Code | Description |
---|---|
403 Forbidden |
Missing API Key Unable to find Client ID from Partner Customers User does not have role permission to use this endpoint |
422 Unprocessable Entity |
Exceeded maximum 30 per page Page parameters must be greater than zero |
{
"policies": [
{
"id": 152,
"name": "Missing cht_owner Tag",
"description": "A block for each asset type",
"user_defined": true,
"creator": "John Doe",
"creator_email": "jdoe@cloudhealthtech.com",
"last_editor": "John Doe",
"last_editor_email": "jdoe@cloudhealthtech.com",
"enabled": true,
"last_evaluation": "2019-05-23 20:19:42 UTC",
"created_at": "2017-08-02 17:39:56 UTC",
},
{
"id": 151,
"name": "CIS AWS Foundations",
"description": "Center for Internet Security (CIS) security benchmark providing best practices securing AWS environments. This policy can be used to validate your adherence to important security recommendations.",
"user_defined": true,
"creator": null,
"creator_email": null,
"last_editor": null,
"last_editor_email": null,
"enabled":true,
"last_evaluation": "2019-05-23 20:19:42 UTC",
"created_at": "2016-11-28 03:57:14 UTC"
}
],
"_links" : {
"next" : {
"href": "cloudhealthtech.com/v1/policies?api_key=4760&per_page=20&page=3"
},
"prev" : {
"href": "cloudhealthtech.com/v1/policies?api_key=4760&per_page=20&page=1"
}
}
}
curl --request GET \
'https://chapi.cloudhealthtech.com/v1/policies?api_key=<client_api_id>&per_page=<max_page_count>&page=<page_number>' \
-H 'Authorization: Bearer <your_api_key>'
-H 'Content-Type: application/json'
Get All Policy Blocks
Retrieve a list of all policy blocks for a policy.
https://chapi.cloudhealthtech.com/v1/policies/:policy_id/policy_blocks
Parameters
-
policy_idrequired
The policy ID of the policy. The policy ID can be retrieved using the Get All Policies endpoint.
-
api_key
String that specifies the unique customer API Key, or Client API ID, that CloudHealth generates. Use this parameter if you are a partner who wants to retrieve a list of all policies belonging to a partner customer. See How to Get Client API ID.
-
per_page
Specify how many results should be displayed per page. Default value is 30.
-
page
Specify the page number for results.
Response Code | Description |
---|---|
403 Forbidden |
Missing API Key Unable to find Client ID from Partner Customers User does not have role permission to use this endpoint |
404 Not Found |
Policy ID not found Policy ID corresponds to a rightsizing policy. Policy API cannot retrieve policy blocks for a rightsizing policy. |
422 Unprocessable Entity |
Exceeded maximum 30 per page Page parameters must be greater than zero |
{
"policy_blocks":[
{ "id": 1511828492778, "name": "Block 1", "last_evaluated": "2019-05-28 11:11:23 UTC"},
{ "id": 1511828492779, "name": "Block 2", "last_evaluated": "2019-05-28 11:11:23 UTC"},
{ "id": 1511828492780, "name": "Block 3", "last_evaluated": "2019-05-28 11:11:23 UTC"},
{ "id": 1511828492781, "name": "Block 4", "last_evaluated": "2019-05-28 11:11:23 UTC"},
{ "id": 1511828492782, "name": "Block 5", "last_evaluated": "2019-05-28 11:11:23 UTC"}
],
"_links": {}
}
curl --request GET \
'https://chapi.cloudhealthtech.com/v1/policies/<policy_id>/policy_blocks?api_key=<client_api_id>&per_page=<max_page_count>&page=<page_number>' \
-H 'Authorization: Bearer <your_api_key>'
-H 'Content-Type: application/json'
Get All Policy Violations
Retrieve a list of all policy violations generated by a policy block.
https://chapi.cloudhealthtech.com/v1/policies/:policy_id/policy_blocks/:policy_block_id/violations
Parameters
-
policy_idrequired
The policy ID of the policy. The policy ID can be retrieved using the Get All Policies endpoint.
-
policy_block_idrequired
The policy block ID of the policy block. The Policy block ID can be retrieved using the Get All Policy Blocks endpoint.
-
api_key
String that specifies the unique customer API Key, or Client API ID, that CloudHealth generates. Use this parameter if you are a partner who wants to retrieve a list of all policies belonging to a partner customer. See How to Get Client API ID.
-
per_page
Specify how many results should be displayed per page. Default value is 30.
-
page
Specify the page number for results.
-
count
Specify the number of violations to return. Default value is 1.
Response Code | Description |
---|---|
403 Forbidden |
Missing API Key Unable to find Client ID from Partner Customers User does not have role permission to use this endpoint |
404 Not Found |
Policy block ID not found |
422 Unprocessable Entity |
Exceeded maximum 30 per page Page parameters must be greater than zero Past violation count parameter must be greater than zero Exceeded maximum 100000 past violations |
{
"id": "6116033458540",
"resource_type": "aws_ec2_instance",
"policy_violations": [
{
"alerts": [
{
"alert_id": 6116034999228,
"evaluation_time": "2019-07-29T20:55:50Z",
"description": "541 M5 instances are large size or larger ",
"severity": "Critical",
"affected_resources": 541,
"uniq_key": ""
}
]
},
{
"alerts": [
{
"alert_id": 6116034999178,
"evaluation_time": "2019-07-24T17:14:04Z",
"description": "541 M5 instances are large size or larger ",
"severity": "Critical",
"affected_resources": 541,
"uniq_key": ""
}
]
},
],
"_links": {
"next": {
"href": "/v1/policies/6116033430880/policy_blocks/6116033458540/violations?count=4&page=2&per_page=2"
}
}
}
curl --request GET \
'https://chapi.cloudhealthtech.com/v1/policies/<policy_id>/policy_blocks/<policy_block_id>/violations?api_key=<client_api_id>&count=5' \
-H 'Authorization: Bearer <your_api_key>'
-H 'Content-Type: application/json'
Get Single Policy Violation
Retrieve a single policy violation and a list of all assets and resources affected by the violation.
https://chapi.cloudhealthtech.com/v1/policies/:policy_id/policy_blocks/:policy_block_id/violations/:violation_id?api_key=:api access key&client_api_id=:client api Id&page=:page_number&per_page=:count_per_page
Parameters
-
api_keyrequired
String that specifies the unique customer API Key, or Client API ID, that CloudHealth generates. Use this parameter if you are a partner who wants to retrieve a list of all policies belonging to a partner customer. See How to Get Client API ID.
-
policy_idrequired
The policy ID of the policy. The policy ID can be retrieved using the Get All Policies endpoint.
-
policy_block_idrequired
The policy block ID of the policy block. The policy block ID can be retrieved using the Get All Policy Blocks endpoint.
-
violation_idrequired
The violation ID of the policy violation. The policy violation ID can be retrieved using the Get All Policy Violations
-
page
Specify the page number for results.
-
per_page
Specify how many results should be displayed per page. Default value is 100.
Response Code | Description |
---|---|
403 Forbidden |
Missing API Key Unable to find Client ID from Partner Customers User does not have role permission to use this endpoint |
404 Not Found |
Violation ID or alert ID not found |
{
"resource_type": "aws_s3_bucket",
"comments": ["TestTestTest"]
"affected_resources" : [
{
"id": 1,
"New": false,
"model_type": "S3 Bucket",
"Name": "cloudhealth-detailed-bills",
"Storage in GB": "1,142,023.68",
"Account Name": "CloudHealth",
"List Price in Month": "$34,260.71",
"Access": "Not public *",
},
{
"id": 2,
"New": false,
"model_type": "S3 Bucket",
"Name": "cloudhealth-detailed-bills-dev",
"Storage in GB": "604.35",
"Account Name": "CloudHealth",
"List Price in Month": "$18.13",
"Access": "Not public *",
},
...
],
"_links": {
"next": {
"href": "policy_violation/5841156436453?api_key=4760&page=2&per_page=33"
}
}
}
curl --request GET \
'https://chapi.cloudhealthtech.com/v1/policies/<policy_id>/policy_blocks/<policy_block_id>/violations/<violation_id>?api_key=<client_api_id>&page=<page_number>&per_page=<count_per_page>' \
-H 'Authorization: Bearer <your_api_key>'
-H 'Content-Type: application/json'
Partner
Introduction to Partner API
An introduction to the Partner API.
Partners and their customers are organized as tenants in a hierarchical, multi-tenant system in the Partner Platform. Customer tenants are subordinates of their corresponding Partner Tenant.
The Partner API allows partners to get reports, metrics, and assets for their customers. In order to use the Partner API, you need to include an additional parameter, the client_api_id
, with each request. CloudHealth generates a unique ID for each partner customer. See How to Get Client API ID.
How to Get Client API ID
To use the Partner API, you need to include an additional parameter, the client_api_id
, with each request. CloudHealth generates a unique ID for each partner customer.
You can get the Client API ID for a customer using the Get All Customers endpoint. You can get the Client API ID for a customer from the CloudHealth Platform. From the left menu, select Partner > Customer > List. If the Client API Id column is not visible in the report, add it by clicking the Edit Columns button.
How to Use the Client API ID with Customer API
The Client API ID is an ID assigned to each partner customer. As a partner, you can use your partner customer’s Client API ID with customer API endpoints to add, remove and view information about your partner customer.
For example, you can use a partner customer’s Client API ID to get a list of queryable reports belonging to that partner customer with the List of Queryable Reports endpoint.
To get a partner customer’s Client API ID, see the How to Get Client API ID topic.
The Client API ID is added to the end of a customer API endpoint. For example:
https://chapi.cloudhealthtech.com/v1/perspective_schemas?client_api_id=<client_api_id>
Specific Customer Report
Retrieve a specific Standard Report for a specific customer tenant.
https://chapi.cloudhealthtech.com/olap_reports/:report-type/:report-id
Parameters
-
client_api_idrequired
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
Refer to Data for Standard Report for more information on retrieving data from a standard report.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Accept: application/json' 'https://chapi.cloudhealthtech.com/olap_reports/cost/history?client_api_id=<customer_api_id>'
#!/usr/bin/env ruby
require "rubygems"
require "net/https"
require "uri"
require "json"
API_ENDPOINT = "https://chapi.cloudhealthtech.com/olap_reports/cost/history"
API_KEY = "<your api key>"
CLIENT_API_ID = "<api id for client>"
# Returns json for requested assets.
def get_report(api_key, client_api_id, interval, query = "")
uri = URI(API_ENDPOINT) + URI.escape("?api_key=#{api_key}&client_api_id=#{client_api_id}&interval=#{interval}&query=#{query}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
response = http.request(request)
raise "Server returned error #{response.code} processing your API request" if response.code != "200"
JSON.parse(response.body)
end
# Fetch all CostHistory objects for the current month
month = Time.now.strftime '%Y-%m-01'
cost_history = get_report(API_KEY, CLIENT_API_ID, 'monthly')
months = cost_history["dimensions"][0]["time"].collect{ |t| t["label"] }
puts "| Month:\tCost"
puts "|----------------------------------|"
months.each_with_index do | month, i |
costs = cost_history["data"].collect{ |month_cost| month_cost[0][0] }
row = "| %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s | %12s |"
puts "| #{month}:\t#{cost_history["data"][i][0][0]}"
end
Assets for Specific Customer
Retrieve a list of assets associated with a specific partner customer.
https://chapi.cloudhealthtech.com/api/search.json?api_version=2
Parameters
-
client_api_idrequired
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID
-
namerequired
String that specifies the unique display name of the customer’s AWS account.
curl 'https://chapi.cloudhealthtech.com/api/search.json?api_version=2&client_api_id=<customer_api_id>
&name=AwsAccount'
-H 'Authorization: Bearer <your_api_key>'
Create Partner Customer
Add a partner customer tenant in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/customers
Parameters
-
namerequired
String that specifies the unique display name of the customer’s AWS account.
-
addressrequired
JSON field that specifies the customer’s mailing address.
-
street1required
Line 1 of street address
-
street2required
Line 2 of street address. Can be blank.
-
cityrequired
City specified as a string
-
staterequired
State specified in abbreviated form. For example, specify Massachusetts as
MA
. For non-US countries, use the full, ASCII-transliterated state names. For example, for Australian state names, specifyAustralian Capital Territory
,New South Wales
,Northern Territory
, and so on. -
zipcoderequired
Zipcode specified as a number
-
countryrequired
Country specified a string
-
-
classification
String that specifies the level of access the customer has in the CloudHealth Platform. Specify as
managed_without_access
(managed customer that does not directly access the CloudHealth Platform) ormanaged_with_access
(managed customer that directly accesses the CloudHealth Platform). -
trial_expiration
Date specified in ISO8601 format that indicates a date in the future when the customer’s trial expires. Beyond this date, users belonging to the customer are unable to access the CloudHealth Platform.
-
billing_contact
String that specifies the email address of customer contact.
-
partner_billing_configuration
Composite JSON field that specifies the configuration for the partner billing engine.
-
enabledrequired
Boolean field that specifies whether partner billing is enabled. Default value is
false
. -
folder
String that specifies the prefix of the S3 folder that contains processed customer bills.
-
-
tags
JSON array that specifies key-value pairs for tags to attach to the customer. Each customer can be assigned a maximum of 20 tags.
-
keyrequired
Tag key
-
valuerequired
Tag value
-
{
"name": "Acme Corp",
"classification": "managed_without_access",
"billing_contact": "john.doe@acmecorp.com",
"trial_expiration": "2016-09-22T00:00:00Z",
"partner_billing_configuration": {
"enabled": "true",
"folder": ""
},
"address": {
"street1": "1 Main St",
"city": "Springfield",
"state": "MA",
"zipcode": "01234",
"country": "US"
},
"tags": [
{
"key": "customer_id", "value": "973532"
},
{
"key": "service_package", "value": "basic_managed"
}
]
}
{
"id": 3947,
"name": "Acme Corp",
"classification": "managed_without_access",
"billing_contact": "john.doe@acmecorp.com",
"margin_percentage": 0.0,
"created_at": "2016-09-15T18:17:04Z",
"updated_at": "2016-09-15T18:17:04Z",
"generated_external_id": "1a2b3c4d5e6f",
"partner_billing_configuration": {
"enabled": false,
"folder": ""
},
"address": {
"street1": "1 Main St",
"city": "Springfield",
"state": "MA",
"zipcode": "01234",
"country": "US"
},
"tags": [
{
"key": "customer_id", "value": "973532"
},
{
"key": "service_package", "value": "basic_managed"
}
],
"_links": {
"self": {
"href": "/v1/customers/3947"
}
}
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name": "Acme Corp",
"classification": "managed_without_access",
"billing_contact": "john.doe@acmecorp.com",
"trial_expiration": "2016-09-22T00:00:00",
"partner_billing_configuration": {
"enabled": "false",
"folder": ""
},
"address": {
"street1": "1 Main St",
"city": "Springfield",
"state": "MA",
"zipcode": "01234",
"country": "US"
}
}'
'https://chapi.cloudhealthtech.com/v1/customers'
Modify Existing Customer
Modify a partner customer tenant that already exists in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/customers/:customer_id
{
"name": "Acme Corporation",
"classification": "managed_with_access"
}
{
"id": XXXX,
"name": "Acme Corporation",
"classification": "managed_with_access",
"billing_contact": "john.doe@acmecorp.com",
"margin_percentage": 0.0,
"created_at": "2016-09-15T13:10:47Z",
"updated_at": "2016-09-15T16:46:34Z",
"generated_external_id": "1a2b3c4d5e6f",
"partner_billing_configuration": {
"enabled": true,
"folder": ""
},
"address": {
"street1": "1 Main St",
"street2": "",
"city": "Springfield",
"State": "MA",
"zipcode": "01234",
"Country": "US"
},
"_links": {
"self": {
"href": "/v1/customers/XXXX"
}
}
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name": "Acme Corporation",
"classification": "managed_with_access"
}'
'https://chapi.cloudhealthtech.com/v1/customers/<customer_id>'
Delete Existing Customer
Delete a partner customer tenant from the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/customers/:customer_id
curl -X "DELETE" 'https://chapi.cloudhealthtech.com/v1/customers/<customer_id>'
-H 'Authorization: Bearer <your_api_key>'
Get Single Customer
Retrieve a specific customer tenant.
https://chapi.cloudhealthtech.com/v1/customers/:customer_id
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customers/<customer_id>'
Get All Customers
Retrieve a list of all customer tenants.
https://chapi.cloudhealthtech.com/v1/customers
Parameters
-
per_page
Integer that specifies the number of assets to return per page.
-
page
Integer that specifies the page to display when results run over multiple pages.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customers?per_page=25'
Statement for Single Customer
Retrieve the billing statement for a specific partner customer.
https://chapi.cloudhealthtech.com/v1/customer_statements
Parameters
-
client_api_idrequired
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID
-
status
String that specifies the status of the statement. Valid values are
Final
orEstimated
. -
billing_period
String that specifies the billing_period of the statement. The date is specified in the format
YYYY-MM
. -
per_page
Integer that specifies the number of assets to return per page.
-
page
Integer that specifies the page to display when results run over multiple pages.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customer_statements/?client_api_id=<client_api_id>&page=1&status=Final&billing_period=2020-12&per_page=2'
{
customer_id : 1211,
cloud: "AWS",
billing_period : "2020-12",
total_amount : 211,523.09,
status : "Final",
detailed_billing_records_generation_time : "2020-12-23 23:59:11",
statement_generation_time : "2020-12-23 23:59:41",
statement_summary_generation_time : "2020-12-23 23:59:53",
currency: {
name: "USD",
symbol: "$"
}
}
Statements for All Customers
Retrieve billing statements for all partner customers.
https://chapi.cloudhealthtech.com/v1/customer_statements
Parameters
-
status
String that specifies the status of the statement. Valid values are
Final
orEstimated
. -
billing_period
String that specifies the billing_period of the statement. The date is specified in the format
YYYY-MM
. -
per_page
Integer that specifies the number of assets to return per page.
-
page
Integer that specifies the page to display when results run over multiple pages.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/v1/customer_statements/?page=1&status=Final&billing_period=2020-12&per_page=2'
{
cloud: "AWS",
billing_period : "2020-12",
total_amount : 211,523.09,
status : "Final",
detailed_billing_records_generation_time : "2020-12-23 23:59:11",
statement_generation_time : "2020-12-23 23:59:41",
statement_summary_generation_time : "2020-12-23 23:59:53",
currency: {
name: "USD",
symbol: "$"
}
}
Connect GovCloud Commercial Account to GovCloud Asset Account
Link a GovCloud account that receives the Detailed Billing Record with the GovCloud account that owns AWS assets.
https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages
Parameters
-
client_api_idrequired
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID
-
JSON documentrequired
Payload containing a single relationship between a GovCloud Commercial Account and a GovCloud Asset Account. See Understand Format of GovCloud Linkage Payload.
GovCloud Commercial Account: The proxy account that contains the costs for the account in the Detailed Billing Record.
GovCloud Asset Account: The account that owns the AWS assets.
The CloudHealth Platform validates the relationship between these two accounts as expressed by the JSON payload by using these considerations.
- Both accounts are owned by the customer associated with the logged in user.
- Neither account is in an existing GovCloud relation
- The GovCloud Asset Account specified must have
is_govcloud
set totrue
, indicating that it is associated with a GovCloud region. - The GovCloud Commercial account is the opposite, must not be in the AWS GovCloud Region.
If any of these validations fails, a list of errors is returned.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -XPOST 'https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages?
client_api_id=<customer_api_id>' -d
{
"govcloud_acct_id": 1,
"commercial_acct_id": 2
}
'{
"id": 8,
"customer_id": XXXX,
"govcloud_acct": 1,
"commercial_acct": 2,
"created_at": "2018-05-16T20:18:58Z",
"updated_at": "2018-05-16T20:18:58Z"
}'
List All GovCloud Linkages Owned by Current Customer
Get all GovCloud linkages that are owned by the current customer.
https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages
Parameters
-
client_api_idrequired
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages?
client_api_id=<customer_api_id>'
[
{
"id": 8,
"customer_id": XXXX,
"govcloud_acct": 1,
"commercial_acct": 2,
"created_at": "2018-05-16T20:18:58Z",
"updated_at": "2018-05-16T20:18:58Z"
},
{
"id": 17,
"customer_id": YYYY,
"govcloud_acct": 3,
"commercial_acct": 6,
"created_at": "2018-05-16T20:18:58Z",
"updated_at": "2018-05-16T20:18:58Z"
},
{
"id": 25,
"customer_id": ZZZZ,
"govcloud_acct": 5,
"commercial_acct": 8,
"created_at": "2018-05-16T20:18:58Z",
"updated_at": "2018-05-16T20:18:58Z"
}
]
Details of Single GovCloud Linkage
Get details for a specific GovCloud linkage.
https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages/:id
Parameters
-
client_api_idrequired
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages/25?
client_api_id=<customer_api_id>
{
"id": 25,
"customer_id": ZZZZ,
"govcloud_acct": 5,
"commercial_acct": 8,
"created_at": "2018-05-16T20:18:58Z",
"updated_at": "2018-05-16T20:18:58Z"
}
Update Single GovCloud Linkage
Update a specific relationship between a GovCloud Commercial Account and GovCloud Asset Account.
https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages/:id
Parameters
-
client_api_idrequired
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
curl -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' 'https://chapi.cloudhealthtech.com/api/v1/govcloud_linkages/25?
client_api_id=<customer_api_id>' -d
'{
"govcloud_acct_id": 17,
"commercial_acct_id": 25
}'
{
"id": 25,
"customer_id": ZZZZ,
"govcloud_acct": 17,
"commercial_acct": 25,
"created_at": "2018-05-16T20:18:58Z",
"updated_at": "2018-05-16T20:18:58Z"
}
Understand Format of GovCloud Linkage Payload
Learn how to format the relationship that establishes a GovCloud linkage.
Familiarize yourself with the format of the payload that you can post to define the linkage between a GovCloud Commercial Account and a GovCloud Asset Account.
GovCloud Commercial Account: The proxy account that contains the costs for the account in the Detailed Billing Record.
GovCloud Asset Account: The account that owns the AWS assets.
Express a linkage between two of these accounts in the following format:
{
"govcloud_acct_id": 1,
"commercial_acct_id": 2
}
In order to get the values of govcloud_acct_id
and commercial_acct_id
use these steps:
- Make a GET request as shown in AWS Accounts in CloudHealth.
- From the response, which contains all AWS accounts associated with the customer, isolate the GovCloud Commercial Account and the GovCloud Asset Account.
- Copy the value of the
id
field for both accounts. - Use the
id
of the GovCloud Commercial Account as the value ofgovcloud_acct_id
and theid
of the GovCloud Asset Account as the value ofcommercial_acct_id
.
Partner AWS Account Assignment
Introduction to Partner AWS Account Assignment API
An introduction to the Account Assignment API.
Use this API to administer AWS accounts that belong to CloudHealth partners and to assign AWS accounts to partner customers for partner-generated billing purposes.
Partner AWS Account Assignment API is available in two versions:
- Version 2: This API supports partner billing blocks and allows partners to assign AWS accounts in billing blocks to partner customers programmatically. Once you have assigned AWS accounts to a partner customer using Version 2 API, you can no longer use Version 1 API to assign, modify, get, or delete account assignments for that partner customer.
- Version 1: This legacy API was created prior to the release of the partner billing block feature, which allows partners to quickly and easily assign multiple accounts in different billing configurations to partner customers at the same time. Consequently, Version 1 API does not support billing blocks.
CloudHealth recommends using Version 2 API to create new account assignments for partner customers and switching Version 1 partner customers to Version 2.
How AWS Account Assignments are Validated (Version 2)
Understand the criteria through which CloudHealth validates Partner AWS Account assignments.
CloudHealth uses the following criteria to validate AWS Account assignments.
- The
owner_id
matches theowner_id
of an AWS account in the partner’s CloudHealth account. - The
owner_id
is assigned to only onetarget_client_api_id
. - You cannot merge two or more AWS accounts into one Partner Generated Billing account in CloudHealth.
- When creating a family billing block, if you enter the
owner_id
of a consolidated AWS account, all AWS accounts linked to the consolidated account are also assigned to the specifiedtarget_client_api_id
.
Create AWS Account Assignment (Version 2)
Assign AWS accounts to Partner Customers in billing blocks for partner-generated billing purposes.
https://chapi.cloudhealthtech.com/v2/aws_account_assignments
Parameters
-
target_client_api_idrequired
String that specifies the unique customer API Key that CloudHealth generates. See How to Get Client API ID.
-
billing_block_name
String that specifies the unique name of the billing block.
-
billing_block_typerequired
JSON field that specifies whether the bill generation type of the billing block is
Family
,Consolidated
, orStandalone
. -
owner_idrequired
The owner ID of the AWS account in the billing block. For family billing blocks, enter the owner ID of the billing family. For consolidated and standalone billing blocks, enter a comma-separated list of the owner IDs of all the AWS accounts in the billing block.
-
payer_account_owner_id
For consolidated billing blocks, specify the owner ID of the designated payer account.
If the corresponding AWS account does not exist in the customer’s CloudHealth account, it is created. If there is an error associated with one AWS account, none of the accounts in the request are assigned.
Response Code | Description |
---|---|
200 OK |
Operation was successful |
422 Unprocessable Entity |
Unprocessable entity |
{
"aws_account_assignments": [
{
"target_client_api_id": 123,
"billing_block_name": "block name1",
"billing_block_type": "Family",
"owner_id": "000000000001"
},
{
"target_client_api_id": 1234,
"billing_block_name": "block name2",
"billing_block_type": "Consolidated",
"owner_id": [
"000000000002",
"000000000003"
],
"payer_account_owner_id": "000000000002"
},
{
"target_client_api_id": 1234,
"billing_block_name": "block name3",
"billing_block_type": "Standalone",
"owner_id": [
"000000000004"
]
}
]
}
{
"aws_account_assignments": [
{
"id": 123333333333,
"owner_id": "000000000001",
"target_client_api_id": 123,
"payer_account_owner_id": "000000000001",
"billing_family_owner_id": "000000000001",
"billing_block_type": "Family",
"billing_block_name": "block name1",
"errors": {}
},
{
"id": 123333333334,
"owner_id": "000000000002",
"target_client_api_id": 1234,
"payer_account_owner_id": "000000000002",
"billing_family_owner_id": "000000000006",
"billing_block_type": "Consolidated",
"billing_block_name": "block name2",
"errors": {}
},
{
"id": 123333333335,
"owner_id": "000000000003",
"target_client_api_id": 1234,
"payer_account_owner_id": "000000000002",
"billing_family_owner_id": "000000000006",
"billing_block_type": "Consolidated",
"billing_block_name": "block name2",
"errors": {}
},
{
"id": 123333333336,
"owner_id": "000000000004",
"target_client_api_id": 1234,
"payer_account_owner_id": "000000000004",
"billing_family_owner_id": "000000000007",
"billing_block_type": "Standalone",
"billing_block_name": "block name3",
"errors": {}
}
]
}
curl --request POST
-H 'Authorization: Bearer <your_api_key>'
-H 'Content-Type: application/json'
-d\
'{
"aws_account_assignments": [
{
"target_client_api_id": 123,
"billing_block_name": "block name1",
"billing_block_type": "Family",
"owner_id": "000000000001"
},
{
"target_client_api_id": 1234,
"billing_block_name": "block name2",
"billing_block_type": "Consolidated",
"owner_id": [
"000000000002",
"000000000003"
],
"payer_account_owner_id": "000000000002"
},
{
"target_client_api_id": 1234,
"billing_block_name": "block name3",
"billing_block_type": "Standalone",
"owner_id": [
"000000000004"
]
}
]
}'\
'https://chapi.cloudhealthtech.com/v2/aws_account_assignments'
Get All AWS Account Billing Blocks (Version 2)
Retrieve a list of all AWS billing blocks and their account assignments.
https://chapi.cloudhealthtech.com/v2/aws_account_assignments
Parameters
-
target_client_api_id
The client API ID of the customer.
Response header
X-Total
: The total number of AWS account assignmentsX-Per-Page
: The number of AWS account assignments that are returned per page
Response content
A JSON object with one field, aws_account_assignments
, whose value is an array of objects with the following fields:
id
: The ID of an AWS account assignmentowner_id
: The AWS ID of the assigned accountpayer_account_owner_id
: The AWS ID of the account whose bills receive the billing line items for the assigned accountbilling_family_owner_id
: The AWS ID of the billing family of the assigned accountbilling_block_type
: The type of billing blockbilling_block_name
: The name of the billing block
The response content is paged if the total number of AWS account assignments is greater than the number that is returned per page.
curl --request GET \
'https://chapi.cloudhealthtech.com/v2/aws_account_assignments/' \
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <your_api_key>'
Get Single AWS Account Assignment (Version 2)
Retrieve information on a single AWS account assignment.
https://chapi.cloudhealthtech.com/v2/aws_account_assignments/:id
Response content
A JSON object with the following fields:
id
: The ID of an AWS account assignmentowner_id
: The AWS ID of the assigned accounttarget_client_api_id
: The client API ID of the customerpayer_account_owner_id
: The AWS ID of the account whose bills receive the billing line items for the assigned accountbilling_family_owner_id
: The AWS ID of the billing family of the assigned accountbilling_block_type
: The type of billing blockbilling_block_name
: The name of the billing block
curl --request GET \
'https://chapi.cloudhealthtech.com/v2/aws_account_assignments/<id>' \
-H 'Authorization: Bearer <your_api_key>'
-H 'Content-Type: application/json'
Update AWS Account Billing Block (Version 2)
Update which AWS account is the designated payer account in an existing consolidated billing block.
https://chapi.cloudhealthtech.com/v2/aws_account_assignments/:target_client_api_id
Parameters
-
billing_block_namerequired
String that specifies the name of the consolidated billing block.
-
payer_account_owner_idrequired
specify the owner ID of the designated payer account for the consolidated billing block.
Response Code | Description |
---|---|
200 OK |
Operation was successful |
422 Unprocessable Entity |
Unprocessable entity |
{
"billing_block_name": "block name2",
"payer_account_owner_id":"000000000003"
}
{
"aws_account_assignments": [
{
"id": 123333333334,
"owner_id": "000000000002",
"target_client_api_id": 1234,
"payer_account_owner_id": "000000000003",
"billing_family_owner_id": "000000000001",
"billing_block_type": "Consolidated",
"billing_block_name": "block name2",
"errors": {}
},
{
"id": 123333333335,
"owner_id": "000000000003",
"target_client_api_id": 1234,
"payer_account_owner_id": "000000000003",
"billing_family_owner_id": "000000000001",
"billing_block_type": "Consolidated",
"billing_block_name": "block name2",
"errors": {}
}
]
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d\
'{
"billing_block_name": "block name2",
"payer_account_owner_id":"000000000003"
}'\
'https://chapi.cloudhealthtech.com/v2/aws_account_assignments/<target_client_api_id>'
Delete AWS Account Assignment (Version 2)
Delete the relationship between an AWS account and the Partner Customer to which it was assigned. Note: If all accounts assigned to a billing block are deleted, the billing block is also deleted.
https://chapi.cloudhealthtech.com/v2/aws_account_assignments/:id
Response Code | Description |
---|---|
200 OK |
Operation was successful |
400 Bad Request |
Unprocessable entity |
curl --request
-H 'Authorization: Bearer <your_api_key>'
-H 'Content-Type: application/json'
DELETE \
'https://chapi.cloudhealthtech.com/v2/aws_account_assignments/<id>' \
How AWS Account Assignments are Validated (Version 1)
Understand the criteria through which CloudHealth validates Partner AWS Account assignments.
CloudHealth uses the following criteria to validate AWS Account assignments.
- All required parameters are provided when you create an AWS account assignment. Review Required Parameters.
- The
owner_id
matches theowner_id
of an AWS account in the partner’s CloudHealth account.- This
owner_id
does not belong to any other AWS account assignment for the partner. - In AWS, the partner’s corresponding AWS account belongs to another account’s consolidated billing family.
- This
- The
customer_id
matches theid
of a customer that belongs to the partner.- This customer has partner billing enabled by setting
enabled
totrue
in itspartner_billing_configuration
.
- This customer has partner billing enabled by setting
- For each customer identified by
customer_id
, all AWS account assignments follow one of these patterns:- All of the customer’s AWS accounts are standalone, each corresponding assignment’s
payer_account_owner_id
matches itsowner_id
. - Only one of the customer’s AWS accounts is assigned as a consolidated account. Its assignment’s
payer_account_owner_id
matches itsowner_id
. All other accounts are assigned as being linked to it. Each corresponding assignment’spayer_account_owner_id
matches the consolidated account’sowner_id
.
- All of the customer’s AWS accounts are standalone, each corresponding assignment’s
- If this is a linked account assignment, where the
payer_account_owner_id
does not match theowner_id
, then thepayer_account_owner_id
matches theowner_id
of a prior AWS account assignment for the samecustomer_id
. These additional criteria apply:- The prior AWS account assignment for the payer account, the one whose
owner_id
matches this assignment’spayer_account_owner_id
—satisfies the following criteria:- The
owner_id
matches thepayer_account_owner_id
.
- The
- In AWS, both accounts belong to the same consolidated billing account family—the partner has a single account whose consolidated billing configuration contains both customer accounts as linked accounts.
- The prior AWS account assignment for the payer account, the one whose
Create AWS Account Assignment (Version 1)
Assign AWS accounts to Partner Customers for partner-generated billing purposes.
https://chapi.cloudhealthtech.com/v1/aws_account_assignments
Parameters
-
owner_idrequired
The AWS ID of the assigned account.
-
customer_idrequired
The ID of the customer to whom the account is assigned. For information on how to get this ID, see Create Partner Customer.
-
payer_account_owner_id
The AWS ID of the account whose bills should receive the billing line items for the assigned account.
If the corresponding AWS account does not exist in the customer’s CloudHealth account, it is created.
Response Code | Description |
---|---|
200 OK |
Operation was successful |
422 Unprocessable Entity |
Unprocessable entity |
Response header
Location
: The location of the created AWS account assignment.
Response content
A JSON object that contains these fields:
- All the fields in the request
id
: The ID of the AWS account assignment that was created
{
"owner_id": "000000000001",
"customer_id": 1,
"payer_account_owner_id": "000000000001"
}
{
"customer_id": 1,
"id": 1,
"owner_id": "000000000001",
"payer_account_owner_id": "000000000001"
}
curl --request POST
-H 'Authorization: Bearer <your_api_key>'
-H 'Content-Type: application/json' -d
'{
"owner_id": "000000000001",
"customer_id": 1,
"payer_account_owner_id": "000000000001"
}'
'https://chapi.cloudhealthtech.com/v1/aws_account_assignments'
Read All AWS Account Assignments (Version 1)
Get information on all AWS account assignments.
https://chapi.cloudhealthtech.com/v1/aws_account_assignments
Response header
X-Total
: The total number of AWS account assignmentsX-Per-Page
: The number of AWS account assignments that are returned per pageLink
: A list of pages if the response content is truncated due to paging
Response content
A JSON object with one field, aws_account_assignments
, whose value is an array of objects with the following fields:
id
: The ID of an AWS account assignmentowner_id
: The AWS ID of the assigned accountcustomer_id
: The ID of the customer to whom the account is assignedpayer_account_owner_id
: The AWS ID of the account whose bills receive the billing line items for the assigned account
The response content is paged if the total number of AWS account assignments is greater than the number that is returned per page.
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/aws_account_assignments/'
Read Single AWS Account Assignment (Version 1)
Get information on a single AWS account assignment.
https://chapi.cloudhealthtech.com/v1/aws_account_assignments
Parameters
-
idrequired
The ID of the AWS account assignment
Response content
A JSON object with one field, aws_account_assignments
, whose value is an array of objects with the following fields:
id
: The ID of an AWS account assignmentowner_id
: The AWS ID of the assigned accountcustomer_id
: The ID of the customer to whom the account is assignedpayer_account_owner_id
: The AWS ID of the account whose bills receive the billing line items for the assigned account
The response content is paged if the total number of AWS account assignments is greater than the number that is returned per page.
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/aws_account_assignments/<id>'
Update AWS Account Assignment (Version 1)
Update an existing AWS account assignment.
https://chapi.cloudhealthtech.com/v1/aws_account_assignments
Parameters
-
idrequired
The ID of the AWS account assignment
-
owner_idrequired
The AWS ID of the assigned account.
-
customer_idrequired
The ID of the customer to whom the account is assigned. For information on how to get this ID, see Create Partner Customer.
-
payer_account_owner_id
The AWS ID of the account whose bills should receive the billing line items for the assigned account.
Response Code | Description |
---|---|
200 OK |
Operation was successful |
422 Unprocessable Entity |
Unprocessable entity |
Response header
Location
: The location of the created AWS account assignment.
Response content
A JSON object that contains these fields:
- All the fields in the request
id
: The ID of the account assignment that was created
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"owner_id": "000000000001",
"customer_id": 1,
"payer_account_owner_id": "000000000001"
}'
'https://chapi.cloudhealthtech.com/v1/aws_account_assignments/<id>'
Delete AWS Account Assignment (Version 1)
Delete the relationship between an AWS account and the Partner Customer to which it was assigned.
https://chapi.cloudhealthtech.com/v1/aws_account_assignments
Parameters
-
idrequired
The ID of the AWS account assignment
Response Code | Description |
---|---|
200 OK |
Operation was successful |
422 Unprocessable Entity |
Unprocessable entity |
Response header
Location
: The location of the created AWS account assignment.
Response content
A JSON object that contains these fields:
- All the fields in the request
id
: The ID of the account assignment that was created
curl --request
-H 'Authorization: Bearer <your_api_key>'
DELETE -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/aws_account_assignments/<id>'
Partner Custom Price Books
Introduction to Price Book API
An introduction to the custom price book API.
Custom price books allow you to develop a custom system of discounts, rates, and adjustments for customers on an individual level. At minimum, the following four API requests must be sent to set up custom price books:
- Create New Price Book
- Test New Price Book
- Assign Price Book to Customer
- Assign Price Book to Account
Note: Custom price books are only available for AWS.
Create New Price Book
Create a new custom price book in the CloudHealth Platform that specifies custom billing rules for your customers.
https://chapi.cloudhealthtech.com/v1/price_books
Parameters
-
book_namerequired
String that specifies the unique display name of the custom price book.
-
specificationrequired
XML-formatted string that specifies the custom billing rules of the price book. See Understand Format of Price Book Specification.
{
"book_name": "Gold tier",
"specification": <XML>
}
{
"price_book": {
"id": XXXX,
"book_name": "Gold tier",
"file_hash": "0aa0d13204c2bb",
"created_at": "2018-01-01",
"updated_at": "2018-01-01"
}
}
curl --request POST -H 'Content-Type: application/json' -d
'{
"book_name": "Gold tier",
"specification": <XML>
}'
'https://chapi.cloudhealthtech.com/v1/price_books?api_key=<your_api_key>'
Modify Existing Price Book
Modify a custom price book that already exists in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/price_books/:price book id
{
"specification": <XML>
}
{
"id": XXXX,
"book_name": "Gold tier",
"created_at": "2018-01-01",
"updated_at": "2018-01-01"
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"specification": <XML>
}'
'https://chapi.cloudhealthtech.com/v1/price_books/<price book id>'
Delete Existing Price Book
Delete a custom price book from the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/price_books/:price book id
curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_books/<price book id>'
Get All Price Books
Retrieve a list of all your custom price books.
https://chapi.cloudhealthtech.com/v1/price_books/
Parameters
-
page
Specify the page number for results
-
per_page
Specify how many results should be displayed per page. Default value is 30.
[{
"id": "1",
"book_name": "Gold Tier",
"created_at": "2018-01-01",
"updated_at": "2018-01-01",
"file_hash": "8b5ad852dc6c11b730"
},
{
"id": "3",
"book_name": "Silver Tier"
"created_at": "2018-01-01",
"updated_at": "2018-01-01",
"file_hash": "0cd8f13406a4ae"
}]
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_books/'
Get Price Book Request
Retrieve a specific custom price book.
https://chapi.cloudhealthtech.com/v1/price_books/:id
{
"id":61,
"book_name":"Test Price Book",
"file_hash":"3d9cb352ba6a00d3211ab8f18507c5ce",
"created_at":"2018-01-01",
"updated_at":"2018-01-25"
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_books/<id>'
Details of Price Book Request
Get details for a specific custom price book.
https://chapi.cloudhealthtech.com/v1/price_books/:id/specification
{
"specification": <XML>
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_books/<id>/specification'
Understand Format of Price Book Specification
Learn how to format the XML specification that establishes a custom price book.
Parameters
-
CHTBillingRulesrequired
Top-level element that specifies the customer by name and customer-id, and whether or not the customer gets a EC2 reserved instance volume discount or rate change.
-
createdBy
String of the email address of the author of the XML specification
-
daterequired
Date string specified in
yyyy-mm-dd
ormm/dd/yyyy
of the date the XML specification was created
-
-
Comment
String for documentation purposes specifying comments on the XML specification. Can be included in any element containing child elements.
-
RuleGrouprequired
Groups together an ordered set of rules that share a common range of applicable dates. Child element of CHTBillingRules.
-
startDate
Date string specified in
yyyy-mm-dd
ormm/dd/yyyy
of the date the rule group should take effect. If no date is specified, the rule group takes effect for all months. -
endDate
Date string specified in
yyyy-mm-dd
ormm/dd/yyyy
of the date the rule group should cease effect. If no date is specified, the rule group takes effect for all months. -
enabled
Boolean field that specifies whether the rule group should be enabled, or
true
, or disabled, orfalse
. Default value istrue
.
-
-
BillingRule
Specifies which products and regions the rule applies to (e.g. which products and regions) and how to apply the discount. Child element of RuleGroup. Discount Rules are evaluated top-down.
-
namerequired
String specifying the name of the rule for documentation purposes
-
includeDataTransfer
Boolean field that specifies whether data transfer costs are covered by the rule. Default value is
true
. -
includeRIPurchases
Boolean field that specifies whether RI purchases are covered by the rule. Default value is
true
.
-
-
BasicBillingRule
Specifies either a percentage discount from 0 to 100 or a fixed unit-price or rate. Child element of BillingRule.
-
billingAdjustmentrequired
Numeric string between 0 and 100 specifying the discount or fixed rate amount
-
billingRuleTyperequired
String specifying whether the discount is
percentDiscount
,percentIncrease
, orfixedRate
-
-
Product
Specifies the product a rule applies to and any constraints about when the rule should apply to the specified product. Usually a child element of BillingRule.
-
productNamerequired
String specifying the name of the product as it appears in the billing file (case sensitive). Enter
ANY
to apply the rule to all products. -
includeDataTransfer
Boolean field that specifies whether data transfer costs are covered for this product. Overrides BillingRule. Default value is
true
. -
includeRIPurchases
Boolean field that specifies whether RI purchases are covered for this product. Overrides BillingRule. Default value is
true
.
-
-
Region
Specifies the region a rule applies to. Usually a child element of Product or BillingRule.
-
namerequired
String in AWS internal format that specifies the name of the region, such as
us-east-2
. To specify the start of the field, use the format[key word]*
. To specify the end of the field, use the format*[key word]
. To specify a key word that appears anywhere in the field, including the start or end, use the format*[key word]*
.
-
-
UsageType
Specifies the usage type a rule applies to. Exclude the region on the billing file to apply UsageType to all regions and include the region to limit UsageType to that region. Child element of Product.
-
namerequired
String specifying the usage type name, formatted to match the usage type name on the billing file without the instance-type prefixes and suffixes. To specify the start of the field, use the format
[key word]*
. To specify the end of the field, use the format*[key word]
. To specify a key word that appears anywhere in the field, including the start or end, use the format*[key word]*
.
-
-
Operation
Specifies the operations a rule applies to. Child element of Product.
-
namerequired
String specifying the operation name, formatted to match the operation name on the billing file. To specify the start of the field, use the format
[key word]*
. To specify the end of the field, use the format*[key word]
. To specify a key word that appears anywhere in the field, including the start or end, use the format*[key word]*
.
-
-
RecordType
Specifies the record types, or line item types, a rule applies to. Child element of Product.
-
name
String specifying the start, end, or key word in the RecordType field. To specify the start of the field, use the format
[key word]*
. To specify the end of the field, use the format*[key word]
. To specify a key word that appears anywhere in the field, including the start or end, use the format*[key word]*
.
-
-
InstanceProperties
Specifies whether the rule applies to the product for specific instance types and sizes and for reservations. Child element of Product.
-
instanceType
String specifying the instance type the rule applies to for this product, such as
t2
-
instanceSize
String specifying the instance size the rule applies to for this product, such as
8xlarge
-
reserved
Boolean field that specifies whether the rule applies to only reserved instances. Default value is
false
.
-
-
LineItemDescription
Specifies a constraint on which products a rule applies to based on the contents of the line item description field in the billing file. Child element of Product.
-
name
String specifying the start, end, or key word in the line item description field. To specify the start of the field, use the format
[key word]*
. To specify the end of the field, use the format*[key word]
. To specify a key word that appears anywhere in the field, including the start or end, use the format*[key word]*
. -
startsWith
String specifying the start of the line item description field
-
contains
String specifying keywords in the line item description field
-
matchesRegex
A Java string specifying a regular expression matching the line item description field
-
-
SavingsPlanOfferingType
Specifies the Savings Plan offering types a rule applies to. Child element of Product.
-
name
String specifying the start, end, or key word in the SavingsPlanOfferingType field. To specify the start of the field, use the format
[key word]*
. To specify the end of the field, use the format*[key word]
. To specify a key word that appears anywhere in the field, including the start or end, use the format*[key word]*
.
-
Familiarize yourself with the format of the XML specification that you can post to define the custom price book for a customer.
XML Formatting: XML is a file format that allows you to enter markup language that is both human-readable and machine-readable. Custom price book specifications are written in XML. To write your specifications, you need an XML editor. If you don’t already have an XML editor, CloudHealth recommends XML Spear.
Rule Order: Custom price book XML specifications process rules in top-down order. The first applicable rule that satisfies all specified constraints for a line item is used, and then no subsequent rules are used for that line item. If no applicable and matching rule is found, the line item will have a 0% calculated price adjustment.
Rule Applicability: Rule applicability is determined by the startDate and endDate attributes in enabled RuleGroup elements. startDates and endDates are inclusive. Whether or not an applicable rule is actually used depends on its order relative to other rules and the constraints it specifies for matching line items.
Example:
<CHTBillingRules createdBy=\"user@partner.com\" date=\"2018-01-01\">
<Comment>This is the Price Book specification for a Customer</Comment>
<RuleGroup>
<BillingRule name=\"10% on EC2\" includeDataTransfer=\"true\">
<BasicBillingRule billingAdjustment=\"10.0\" billingRuleType=\"percentDiscount\"/>
<Product productName=\"Amazon Elastic Compute Cloud\"/>
</BillingRule>
<BillingRule name\"$0.50 flat rate for CloudFront\">
<BasicBillingRule billingAdjustment=\"0.5\" billingRuleType=\"fixedRate\"/>
<Product productName=\"Amazon CloudFront\"/>
</BillingRule>
<BillingRule name=\"10% markup on RDS charges in us-east-1\">
<BasicBillingRule billingAdjustment=\"10.0\" billingRuleType=\"percentIncrease\">
<Product productName=\"Amazon Relational Database System\">
<Region name=\"us-east-1\"/>
</Product>
</BillingRule>
</RuleGroup>
</CHTBillingRules>
Understand Price Book Test Results
Learn how to review the results of the custom price book XML specification test.
Familiarize yourself with the format of the custom price book XML specification test results that you can verify whether the custom price book is accurate before you assign the price book to customers.
Test Result Formats: Test results are returned in aggregations that contain the calculated discounts and rates according to the custom price book XML specification. Three aggregations are provided in the following hierarchy:
- Product-level
- Usage type-level
- Operation level
Review and Revise: Review the three aggregations and verify whether all discounts, rates, and adjustments for each product appear as expected. If any of the discounts, rates, or adjustments are incorrect, then there are mistakes present in the XML specification that must be corrected. There are several possible reasons why the XML specification is incorrect:
- The data was incorrectly entered into the XML specification. Review the XML specification and verify that all discount, rate, and adjustment amounts are correct for each product.
- The order is incorrect. The XML specification evaluates each rule in top-down order. Once a product has a discount, rate, or adjustment applied to it, the XML specification ignores all further price adjustments applied to that product. Verify that the rule order is correct in the XML specification.
- The product name is misspelled. The productName attribute must exactly match the product name in the billing file and is case sensitive. For example, a discount to
Amazon Elastic Compute cloud
will be ignored because the last word in the product name isn’t properly capitalized. Verify that all product names in the XML specification are correctly spelled and formatted.
Once you have corrected the XML specification, modify the custom price book in CloudHealth and rerun the test.
Assign Price Book to Customer
Assign a custom price book to a customer or customers.
https://chapi.cloudhealthtech.com/v1/price_book_assignments
Parameters
-
price_book_idrequired
Integer that specifies which custom price book to use.
-
target_client_api_idrequired
Integer that specifies the assigned customer’s client_api_id.
{
"price_book_id": XXXX,
"target_client_api_id": <client_api_id>
}
{
"id": <int>,
"target_client_api_id": <client_api_id>,
"price_book_id": XXXX,
"created_at": "2018-01-01",
"updated_at": "2018-01-01"
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"price_book_id": XXXX,
"target_client_api_id": <client_api_id>
}'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments'
Modify Existing Price Book Customer Assignment
Modify which custom price book is assigned to a customer.
https://chapi.cloudhealthtech.com/v1/price_book_assignments/:id
{
"price_book_id": XXXX
}
{
"id": 6,
"target_client_api_id": <client_api_id>,
"price_book_id": XXXX,
"created_at": "2018-01-01",
"updated_at": "2018-01-01"
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"price_book_id": XXXX
}'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments/<id>'
Delete Existing Price Book Customer Assignment
Delete a custom price book’s customer assignment.
https://chapi.cloudhealthtech.com/v1/price_book_assignments/:id
curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments/<id>'
Get All Price Book Customer Assignments
Retrieve a list of all customers assigned to a custom price book.
https://chapi.cloudhealthtech.com/v1/price_book_assignments
Parameters
-
page
Specify the page number for results
-
per_page
Specify how many results should be displayed per page. Default value is 30.
-
target_client_api_id
Specifies the assigned customer’s
client_api_id
.
{
"id": 1,
"price_book_id": XXXX,
"target_client_api_id": <client_api_id>,
"created_at": "2018-01-01",
"updated_at": "2018-01-01"
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments'
Get Price Book Customer Assignment
Retrieve one customer assigned to a custom price book.
https://chapi.cloudhealthtech.com/v1/price_book_assignments/:id
{
"id": 1,
"price_book_id": XXXX,
"target_client_api_id": <client_api_id>,
"created_at": "2018-01-01",
"updated_at": "2018-01-01"
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments/<id>'
Assign Price Book to Account
Assign a custom price book to a customer’s AWS accounts. The custom price book must have already been assigned to the customer.
https://chapi.cloudhealthtech.com/v1/price_book_account_assignments
Parameters
-
price_book_assignment_idrequired
Integer that specifies which custom price book to use. This ID can be retrieved from the Get All Price Book Customer Assignments endpoint.
-
billing_account_owner_id
String that specifies which account to assign the custom price books to. Enter
ALL
to assign the custom price book to all of the assigned customer’s accounts or enter a single account ID to assign the price book to one account. To assign the custom price book to multiple (but not all) accounts belonging to a customer, use the billing_account_owner_ids parameter. -
billing_account_owner_ids
Comma-separated list that specifies which accounts to assign the custom price books to. Use to assign the custom price book to multiple (but not all) of a customer’s accounts. To assign the price book to only one account, or to assign the price book to all accounts belonging to the customer, use the billing_account_owner_id parameter.
{
"price_book_assignment_id": 6,
"billing_account_owner_ids": ["343243","3432423"]
}
{
"price_book_assignment_id": 6,
"billing_account_owner_id": "12345"
}
{
"price_book_assignment_id": 6,
"billing_account_owner_id": "ALL"
}
{
"price_book_account_assignments": [
{
"id": 52,
"target_client_api_id": <client_api_id>,
"price_book_assignment_id": 6,
"billing_account_owner_id": "343243"
},
{
"id": 53,
"target_client_api_id": <client_api_id>,
"price_book_assignment_id": 6,
"billing_account_owner_id": "3432423"
}
]
}
{
"id": 54,
"target_client_api_id": <client_api_id>,
"price_book_assignment_id": 6,
"billing_account_owner_id": "ALL"
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"price_book_assignment_id": XXXX,
"billing_account_owner_id": "ALL"
}'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments'
Modify Existing Price Book Account Assignment
Modify which AWS account a custom price book is assigned to.
https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/:id
{
"billing_account_owner_id": <string>
}
{
"id": 36,
"target_client_api_id": <client_api id>,
"price_book_assignment_id": <int>,
"billing_account_owner_id": <string>
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"billing_account_owner_id": <string>
}'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/<id>'
Delete Existing Price Book Account Assignment
Delete a custom price book’s AWS account assignment.
https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/:id
curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/<id>'
Get All Price Book Account Assignments
Retrieve a list of all AWS accounts assigned to a custom price book.
https://chapi.cloudhealthtech.com/v1/price_book_account_assignments
Parameters
-
page
Specify the page number for results
-
per_page
Specify how many results should be displayed per page. Default value is 30.
{
"price_book_account_assignments": [
{
"id": 55,
"target_client_api_id": <client_api id>,
"price_book_assignment_id": <int>,
"billing_account_owner_id": <string>
},
{
"id": 56,
"target_client_api_id": <client_api id>,
"price_book_assignment_id": <int>,
"billing_account_owner_id": <string>
}
]
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments'
Get Price Book Account Assignment
Retrieve one AWS account assigned to a custom price book.
https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/:id
{
"id": 56,
"target_client_api_id": <client_api id>,
"price_book_assignment_id": <int>,
"billing_account_owner_id": <string>
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/price_book_account_assignments/<id>'
Get Specific Customer Price Book Assignments
Run a query to get specific channel customer assignments.
https://chapi.cloudhealthtech.com/v1/price_book_assignments
{
"target_client_api_id": <string>
}
{
"id": 6,
"target_client_api_id": <client_api_id>,
"price_book_id": XXXX,
"created_at": "2018-01-01",
"updated_at": "2018-01-01"
}
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d '{"target_client_api_id": <client_api_id>}'
'https://chapi.cloudhealthtech.com/v1/price_book_assignments'
Partner Billing Rules
Introduction to Billing Rule API
An introduction to the Billing Rule API.
Partner Billing Rules allow partners to adjust AWS and Azure customer costs globally or for specific customers. CloudHealth applies these adjustments when generating the bills for individual customers.
The Billing Rules API allows partner customers to create, modify, and delete AWS support and custom line item billing rules.
How to Get Billing Rule ID
In order to use some Billing Rule endpoints, you need to provide the partner_billing_rule_id
. CloudHealth generates a unique ID for each billing rule. You can get the Billing Rule ID for an organization from the CloudHealth Platform. From the left menu, go to Partner > Partner Billing > Billing Rules and view or edit the organization. The Billing Rule ID appears in the browser URL. Here’s an example URL:
https://apps.cloudhealthtech.com/partner_billing_rules/57XXXXXXXXX96/edit
Here, 57XXXXXXXXX96
is the Billing Rule ID.
The Billing Rule ID can also be retrieved using the Create Billing Rule and Get All Billing Rules endpoints.
How to Get Azure Enterprise Agreement ID
In order to use some Billing Rule endpoints, you may need to provide the Azure Enterprise Agreement (EA) ID. CloudHealth generates a unique ID for each EA. You can get the Azure EA ID from the CloudHealth Platform. From the left menu, go to Setup > Accounts > Azure Enrollment and view or edit the EA. The Azure EA ID appears in the browser URL. Here’s an example URL:
https://apps.cloudhealthtech.com/azure_enrollments/20XXXXXXX19/edit
Here, 20XXXXXXX19
is the Azure EA ID.
Create New Partner Billing Rule
Add a new partner billing rule in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/partner_billing_rules
Parameters
-
namerequired
String that specifies the unique name of the billing rule.
-
cloudrequired
Specify the cloud the billing rule applies to as either
aws
orazure
. -
add_target_customers
Enter the client API keys of the AWS customers that the billing rule applies to. To apply the rule to all customers, enter
all
. -
add_enterprise_agreements
Specify which EA customers the billing rule applies to. Enter the EA’s client API key and the Azure EA ID in a comma-separated list.
-
add_csp_customers
Enter the client API keys of the Microsoft CSP customers that the billing rule applies to. To apply the rule to all customers, enter
all
. -
billing_rule_typerequired
Specify whether the billing rule is
custom
(a custom line item) orsupport
(an AWS support rule). You can only create an AWS support rule for a rule whose cloud isaws
. -
rule_actionrequired
String that specifies what action the billing rule should take. For custom line items, enter
flat_fee
(flat fee charge or credit) orspend_ratio
(percentage of spend charge or credit). For AWS support rules, enterflat_fee
(flat fee charge),list_price
(AWS list price charge),percentage_discount
(percentage discount charge),suppress_charge
(charges suppressed for this item), orcustom_tier
(custom pricing charge). -
rule_scope
Specify whether the scope of an AWS Support billing rule is
per_account
orper_billing_family
. Default value isper_account
. -
support_tier
Specify whether the support tier of an AWS Support billing rule is
developer
,business
, orenterprise
. Default value isdeveloper
. -
flat_fee_cost
For AWS support rules with a rule action of
flat_fee
, specify the flat fee charge amount. Required for flat fee AWS support rules. -
charge_percentage_discount
For AWS support rules with a rule action of
percentage_discount
, specify the percentage discount charge amount. Required for percentage discount AWS support rules. -
pricing_info
For AWS support rules with a rule action of
custom_tier
, specify in a JSON array the custom pricing structure. Custom tier pricing is structured as either a flat fee or a percentage of monthly AWS usage in four tiered spend ranges, whichever is greater. For example, the greater of either $100 or 10% for monthly AWS usage $0-$10,000; 7% for $10,000-$80,000; 5% for $80,000-$250,000; 3% for $250,000 and up. See AWS Support Plan Pricing for more information on AWS Support custom pricing. Required for custom tier pricing AWS support rules.-
min_feerequired
Enter the flat fee that should be charged if the percentage of AWS spend is lower than this amount. For example,
100
. -
min_spend_rangerequired
Enter the lower AWS spend range for each of the four spend range tiers in a comma-separated list. For example,
[0, 10000, 80000, 250000]
-
min_spend_raterequired
Enter the percentage charged to each of the four AWS spend range tiers in a comma-separated list. For example,
[10,7,5,3]
.
-
-
start_month
For custom line items, specify the month the billing rule should take effect. The date string has the format
YYYY-MM
. Default value is the current month. -
frequency
For custom line items, specify whether the billing rule is
one_time
orrecurring
. Default value isone_time
. -
product_name
For custom line items, specify the product name of the billing rule. This name appears as a line item in the customer’s bill. Required for custom line items.
-
product_description
For custom line items, specify the product description of the billing rule. This description appears in the line item in the customer’s bill. Required for custom line items.
-
type
For custom line items, specify whether the billing rule is a
charge
orcredit
. Default value ischarge
. -
apply_flat_fee_cost
For custom line items with a rule action of
flat_fee
, enter specify the flat fee amount. Required for flat fee custom line item rules. -
apply_rate_in_percentage
For custom line items with a rule action of
spend_ratio
, specify the percentage of spend amount. Required for percentage of spend custom line item rules. -
add_spend_ratio_as_custom_line_item
For Azure custom line items with a rule action of
spend_ratio
, specify whether to apply the percentage credits and charges once to the main subscription (true
) or to each line item in the bill (false
). The default value isfalse
.
{
"name": "Business support",
"cloud": "aws",
"billing_rule_type": "custom_tier",
"add_target_customers": [1,2,3],
"rule_action": "custom_tier",
"rule_scope": "per_billing_family",
"support_tier": "business",
"pricing_info":{
"min_fee": 100,
"min_spend_range":[0,10000, 80000, 250000],
"min_spend_rate": [10,7,5,3]
}
}
{
"name": "Customer markup",
"add_target_customers": [1,2,3],
"cloud": "aws",
"billing_rule_type": "custom",
"rule_action": "spend_ratio",
"start_month": "2019-05",
"frequency": "recurring",
"product_name": "markup",
"product_description": "markup",
"type": "charge",
"apply_rate_in_percentage": 5
}
{
"name": "Customer markup",
"add_csp_customers":[3,4]
"add_enterprise_agreements": {<client_api_key>:[234,456], "2":[457,890]},
"billing_rule_type": "custom",
"cloud": "azure",
"rule_action": "flat_fee",
"start_month": "2019-05",
"frequency": "recurring",
"product_name": "markup",
"product_description": "markup",
"type": "charge",
"apply_flat_fee_cost": 1000
}
{
"name": "Customer markup",
"product_name": "markup",
"product_description": "markup",
"rule_scope": "per_account",
"billing_rule_type": "custom",
"cloud": "aws",
"target_customers": [1,2,3],
"start_month": "2019-05",
"frequency": "recurring",
"type": "charge",
"rate_in_percentage": 5
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name": "Customer markup",
"add_target_customers": [1,2,3],
"cloud": "aws",
"billing_rule_type": "custom",
"rule_action": "spend_ratio",
"start_month": "2019-05",
"frequency": "recurring",
"product_name": "markup",
"product_description": "markup",
"type": "charge",
"apply_rate_in_percentage": 5
}'
'https://chapi.cloudhealthtech.com/v1/partner_billing_rules'
Modify Existing Billing Rule
Modify an existing billing rule in the CloudHealth Platform. You cannot modify the billing rule’s cloud, billing rule type, or rule action.
https://chapi.cloudhealthtech.com/v1/partner_billing_rules/:partner_billing_rule_id
Parameters
-
namerequired
String that specifies the unique name of the billing rule.
-
add_target_customers
Enter the client API keys of the AWS customers that the billing rule applies to. To apply the rule to all customers, enter
all
. -
remove_target_customers
Enter the client API keys of the AWS customers that should be removed from the billing rule.
-
add_enterprise_agreements
Specify which EA customers the billing rule applies to. Enter the EA’s client API key and the Azure EA ID in a comma-separated list.
-
remove_enterprise_agreements
Specify which EA customers should be removed from the billing rule. Enter the EA’s client API key and the Azure EA ID in a comma-separated list.
-
add_csp_customers
Enter the client API keys of the Microsoft CSP customers that the billing rule applies to. To apply the rule to all customers, enter
all
. -
remove_csp_customers
Enter the client API keys of the Microsoft CSP customers that should be removed from the billing rule.
-
rule_scope
Specify whether the scope of an AWS Support billing rule is
per_account
orper_billing_family
. Default value isper_account
. -
support_tier
Specify whether the support tier of an AWS Support billing rule is
developer
,business
, orenterprise
. Default value isdeveloper
. -
flat_fee_cost
For AWS support rules with a rule action of
flat_fee
, specify the flat fee charge amount. Required for flat fee AWS support rules. -
charge_percentage_discount
For AWS support rules with a rule action of
percentage_discount
, specify the percentage discount charge amount. Required for percentage discount AWS support rules. -
pricing_info
For AWS support rules with a rule action of
custom_tier
, specify in a JSON array the custom pricing structure. Custom tier pricing is structured as either a flat fee or a percentage of monthly AWS usage in four tiered spend ranges, whichever is greater. For example, the greater of either $100 or 10% for monthly AWS usage $0-$10,000; 7% for $10,000-$80,000; 5% for $80,000-$250,000; 3% for $250,000 and up. See AWS Support Plan Pricing for more information on AWS Support custom pricing. Required for custom tier pricing AWS support rules.-
min_feerequired
Enter the flat fee that should be charged if the percentage of AWS spend is lower than this amount. For example,
100
. -
min_spend_rangerequired
Enter the lower AWS spend range for each of the four spend range tiers in a comma-separated list. For example,
[0, 10000, 80000, 250000]
-
min_spend_raterequired
Enter the percentage charged to each of the four AWS spend range tiers in a comma-separated list. For example,
[10,7,5,3]
.
-
-
start_month
For custom line items, specify the month the billing rule should take effect. The date string has the format
YYYY-MM
. Default value is the current month. -
frequency
For custom line items, specify whether the billing rule is
one_time
orrecurring
. Default value isone_time
. -
product_name
For custom line items, specify the product name of the billing rule. This name appears as a line item in the customer’s bill. Required for custom line items.
-
product_description
For custom line items, specify the product description of the billing rule. This description appears in the line item in the customer’s bill. Required for custom line items.
-
type
For custom line items, specify whether the billing rule is a
charge
orcredit
. Default value ischarge
. -
apply_flat_fee_cost
For custom line items with a rule action of
flat_fee
, enter specify the flat fee amount. Required for flat fee custom line item rules. -
apply_rate_in_percentage
For custom line items with a rule action of
spend_ratio
, specify the percentage of spend amount. Required for percentage of spend custom line item rules. -
add_spend_ratio_as_custom_line_item
For Azure custom line items with a rule action of
spend_ratio
, specify whether to apply the percentage credits and charges once to the main subscription (true
) or to each line item in the bill (false
). The default value isfalse
.
{
"name": "Customer markup 23",
"add_enterprise_agreements": {"1":[2]},
"remove_csp_customers":[111]
"start_month": "2019-06",
"frequency": "one_time",
"apply_rate_in_percentage": 4
}
{
"id": 1,
"name": "Customer markup 23",
"product_name": "markup",
"product_description": "markup",
"billing_rule_type": "custom",
"cloud": "azure",
"csp_customers": [1,2],
"enterprise_agreements":{"1":[2]},
"start_month": "2019-06",
"frequency": "one_time",
"type": "charge",
"rate_in_percentage": 4,
"add_spend_as_custom_line_item": true
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name": "Customer markup 23",
"add_enterprise_agreements": {"1":[2]},
"remove_csp_customers":[111]
"start_month": "2019-06",
"frequency": "one_time",
"apply_rate_in_percentage": 4
}'
'https://chapi.cloudhealthtech.com/v1/partner_billing_rules/<partner_billing_rule_id>'
Get Single Billing Rule
Retrieve a specific billing rule.
https://chapi.cloudhealthtech.com/v1/partner_billing_rules/:partner_billing_rule_id
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/partner_billing_rules/<partner_billing_rule_id>'
Delete Existing Billing Rule
Delete a billing rule from the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/partner_billing_rules/:partner_billing_rule_id
curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/partner_billing_rules/<partner_billing_rule_id>'
Azure Service Principals
Introduction to Azure Service Principal API
An introduction to the Azure Service Principal API.
The Azure service principal defines the access an application such as CloudHealth has to your Azure Portal data. Use this API to connect an Azure service principal to the CloudHealth Platform.
Depending on your account type, you need to complete different kinds of setup prior to using the Azure service principal API.
- Enterprise Agreement/GovCloud direct customer:
- Complete steps 1-5 in the Enable Azure Accounts in CloudHealth topic.
- Replace step 6 with the Connect Service Principal endpoint.
- Pay As You Go direct customer:
- Complete steps 1-2 in the Enable Azure Accounts in CloudHealth topic.
- Replace step 3 with the Connect Service Principal endpoint.
- Partner customer:
- Complete steps 1-2 in the Configure Microsoft CSP Partner Customer topic.
- Replace steps 3 and 4 with the Connect Service Principal endpoint to connect the service principal with both the partner and the partner customer.
The Azure Service Principal API allows direct customers, partners, and partner customers to connect their service principal to CloudHealth. partners to get reports, metrics, and assets for their customers. In order to use some of the Azure Service Principal endpoints, you need to provide the sp_id
. CloudHealth generates a unique ID for each service principal. See How to Get Service Principal ID.
How to Get Service Principal ID
In order to use some of the Azure Service Principal endpoints, you need to provide the sp_id
. CloudHealth generates a unique ID for each service principal.
You can get the Service Principal ID for a customer’s service principal from the CloudHealth Platform. From the left menu, go to Setup > Accounts > Azure Service Principal and open the service principal. The ID of the service principal appears in the browser URL. Here’s an example URL:
https://apps.cloudhealthtech.com/azure_service_principals/33672XXXXXX68
Here, 33672XXXXXX68
is the service principal ID.
The Service Principal ID can also be retrieved using the Get All Existing Service Principals endpoint.
Connect Service Principal in CloudHealth
Connect a service principal to a customer, partner customer, and/or partner in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/azure_service_principals
Parameters
-
namerequired
String that specifies the name of the service principal.
-
client_idrequired
The client ID, or application ID, registered with the service principal.
-
client_secretrequired
The secret key for the client ID.
-
tenant_idrequired
The tenant ID, or directory ID, of the customer tenant.
-
sp_type
JSON field that specifies whether the service principal type is
global
orgovcloud
. Default value isglobal
. -
is_metrics_enabled
Boolean field that specifies whether metrics collection is enabled. Default value is
true
. -
disable_assets_collection
JSON field that specifies whether to not collect data for specific assets. Enter
true
to disable asset collection for the specified asset. Default value for all assets isfalse
.-
AzureActiveDirectoryRoleDefinition
Boolean field that specifies whether to not collect data for the Azure Active Directory Role Definition asset. Default value is
false
. -
AzureActiveDirectoryUser
Boolean field that specifies whether to not collect data for the Azure Active Directory Users asset. Default value is
false
. -
AzureKeyVaultKey
Boolean field that specifies whether to not collect data for the Azure Key Vault Keys asset. Default value is
false
. -
AzureKeyVaultSecret
Boolean field that specifies whether to not collect data for the Azure Key Vault Secrets asset. Default value is
false
. -
AzureSqlDatabaseAuditing
Boolean field that specifies whether to not collect data for the Azure Sql Database Auditing asset. Default value is
false
. -
AzureSqlDatabaseThreatDetection
Boolean field that specifies whether to not collect data for the Azure Sql Database Threat Detection asset. Default value is
false
. -
AzureSqlServerAuditing
Boolean field that specifies whether to not collect data for the Azure Sql Server Auditing asset. Default value is
false
. -
AzureSqlServerFirewallRule
Boolean field that specifies whether to not collect data for the Azure SQL Server Firewall Rule asset. Default value is
false
. -
AzureSqlServerThreatDetection
Boolean field that specifies whether to not collect data for the Azure Sql Server Threat Detection asset. Default value is
false
. -
AzureSubscriptionSecurityPolicy
Boolean field that specifies whether to not collect data for the Azure Subscription Security Policy asset. Default value is
false
.
-
-
create_sp_for_partner_customer
String that specifies the client API ID of the partner customer. Use this parameter only when connecting the service principal to a partner customer and partner in CloudHealth. For information on how to get this ID, see How to Get Client API ID.
{
"name": "Production SP",
"sp_type": "govcloud" ,
"client_id": "xndencrnvcr",
"client_secret": "cbdefeb",
"tenant_id": "356dnsdn",
"is_metrics_enabled": false,
"disable_assets_collection": [{
"AzureKeyVaultKey": true,
"AzureKeyVaultSecret": true
}],
"create_sp_for_partner_customer": <client_api_id>
}
{
"name": "Production SP",
"sp_type": "govcloud" ,
"client_id": "xndencrnvcr",
"client_secret": "cbdefeb",
"tenant_id": "356dnsdn",
"is_metrics_enabled": false,
"disable_assets_collection": [{
"AzureKeyVaultKey": true,
"AzureKeyVaultSecret": true
}],
}
{
"id": 1,
"name": "Production SP",
"sp_type": "govcloud" ,
"client_id": "xndencrnvcr",
"tenant_id": "356dnsdn",
"is_metrics_enabled": false,
"created_at": "timestamp",
"updated_at": "timestamp"
"status" :[{
"status": "healthy",
"status_at": "timestamp"
}],
"disable_assets_collection": [{
"AzureKeyVaultKey": true,
"AzureKeyVaultSecret": true
}]
},
{
"id": 2,
"name": "Production SP",
"sp_type": "govcloud" ,
"client_id": "xndencrnvcr",
"tenant_id": "356dnsdn",
"is_metrics_enabled": false,
"created_at": "timestamp",
"updated_at": "timestamp"
"status" :[{
"status": "healthy",
"status_at": "timestamp"
}],
"disable_assets_collection": [{
"AzureKeyVaultKey": true,
"AzureKeyVaultSecret": true
}]
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name": "Production SP",
"sp_type": "govcloud" ,
"client_id": "xndencrnvcr",
"client_secret": "cbdefeb",
"tenant_id": "356dnsdn",
"is_metrics_enabled": false,
"disable_assets_collection": [{
"AzureKeyVaultKey": true,
"AzureKeyVaultSecret": true
}],
"create_sp_for_partner_customer": <client_api_id>
}'
'https://chapi.cloudhealthtech.com/v1/azure_service_principals'
Modify Existing Service Principal
Modify a service principal that is already connected in the CloudHealth Platform. The client_id
, tenant_id
and sp_type
parameters cannot be modified.
https://chapi.cloudhealthtech.com/v1/azure_service_principals/:sp_id
Parameters
-
namerequired
String that specifies the name of the service principal.
-
client_secretrequired
The secret key for the client ID.
-
is_metrics_enabled
Boolean field that specifies whether metrics collection is enabled. Default value is
true
. -
modify_sp_for_partner_customer
String that specifies the client API ID of the partner customer. Use this parameter only when modifying the service principal of a partner customer and partner in CloudHealth. For information on how to get this ID, see How to Get Client API ID.
-
disable_assets_collection
JSON field that specifies whether to not collect data for specific assets. Enter
true
to disable asset collection for the specified asset. Default value for all assets isfalse
.
{
"name": "Production SP 1",
"client_secret": "cbdefeb",
"is_metrics_enabled": true,
"modify_sp_for_partner_customer": <client_api_id>
"disable_assets_collection"
[{
"AzureKeyVaultKey" : true,
"AzureKeyVaultSecret": false
}]
}
{
"name": "Production SP 1",
"client_secret": "cbdefeb",
"is_metrics_enabled": true,
"disable_assets_collection"
[{
"AzureKeyVaultKey": true,
"AzureKeyVaultSecret": false
}]
}
{
"id":1,
"name": "Production SP 1",
"sp_type":"global" ,
"client_id": "xndencrnvcr",
"tenant_id": "356dnsdn",
"is_metrics_enabled": true,
"created_at": "timestamp",
"updated_at": "timestamp"
"status" :[{
"status": "healthy",
"status_at": "timestamp"
}],
"disable_assets_collection": [{
"AzureKeyVaultKey": true
}]
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name": "Production SP 1",
"client_secret": "cbdefeb",
"is_metrics_enabled":true,
"modify_sp_for_partner_customer": <client_api_id>
"disable_assets_collection"
[{
"AzureKeyVaultKey" : true,
"AzureKeyVaultSecret":false
}]
}'
'https://chapi.cloudhealthtech.com/v1/azure_service_principals/<sp_id>'
Get All Existing Service Principals
Retrieve a list of all service principals.
https://chapi.cloudhealthtech.com/v1/azure_service_principals
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/azure_service_principals/'
Details of Service Principal
Get details for a specific service principal.
https://chapi.cloudhealthtech.com/v1/azure_service_principals/:sp_id
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/azure_service_principals/<sp_id>/'
Azure Partner
Introduction to Microsoft CSP Partner API
An introduction to the Microsoft CSP Partner API.
Microsoft CSP partners and their customers are organized as tenants in a hierarchical, multi-tenant system in the Partner Platform. Customer tenants are subordinates of their corresponding Partner Tenant.
The Partner API allows partners to add their customer tenants to the Partner Platform.
How to Get Client API ID
In order to use the Partner API, you need to include an additional parameter, the client_api_id
, with each request. CloudHealth generates a unique ID for each partner customer.
You can get the Client API ID for a customer using the Get All Customers endpoint. You can get the Client API ID for a customer from the CloudHealth Platform. From the left menu, select Partner > Customer > List. If the Client API Id column is not visible in the report, add it by clicking the Edit Columns button.
How to Get Database Partner Customer ID
In order to use some of the Azure Partner endpoints, you need to provide the db_partner_customer_id
. CloudHealth generates a unique ID for each partner customer.
You can get the Database Partner Customer ID for a partner customer from the CloudHealth Platform. From the left menu, go to Setup > Accounts > Azure Partner Customers and open the partner customer. The database ID of the partner customer appears in the browser URL. Here’s an example URL:
https://apps.cloudhealthtech.com/azure_partner_customers/5XXXXXXXXXX25
Here, 5XXXXXXXXXX25
is the Database Partner Customer ID.
The Database Customer ID can also be retrieved using the Get Single Partner Customer endpoint.
Create CSP Partner Customer
Add a Microsoft CSP partner customer tenant in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v2/customers
Parameters
-
namerequired
String that specifies the unique display name of the customer’s Azure account.
-
azure_customer_id
The Azure customer ID of the customer tenant. Use this parameter when the customer tenant has an address entered in the Azure Portal. If the customer tenant does not have an address entered in the Azure Portal, replace the
azure_customer_id
parameter with theaddress
parameter. -
address
JSON field that specifies the customer’s mailing address. Use this parameter when the customer tenant does not have an address entered in the Azure Portal. If the customer tenant has an address entered in the Azure Portal, use the
azure_customer_id
instead.-
street1required
Line 1 of street address
-
street2
Line 2 of street address. Can be blank.
-
cityrequired
City specified as a string
-
staterequired
State specified in abbreviated form. For example, specify Massachusetts as
MA
. For non-US countries, use the full, ASCII-transliterated state names. For example, for Australian state names, specifyAustralian Capital Territory
,New South Wales
,Northern Territory
, and so on. -
zipcoderequired
Zipcode specified as a number
-
countryrequired
Country specified a string
-
-
classification
String that specifies the level of access the customer has in the CloudHealth Platform. Specify as
managed_without_access
(managed customer that does not directly access the CloudHealth Platform) ormanaged_with_access
(managed customer that directly accesses the CloudHealth Platform). The default value is `managed_without_access’. -
trial_expiration_date
Date specified in ISO8601 format that indicates a date in the future when the customer’s trial expires. Beyond this date, users belonging to the customer are unable to access the CloudHealth Platform.
-
billing_contact
String that specifies the email address of customer contact.
-
partner_billing_configuration
Composite JSON field that specifies the configuration for the partner billing engine.
-
enabledrequired
Boolean field that specifies whether partner billing is enabled. Default value is
false
. -
folder
String that specifies the prefix of the S3 folder that contains processed customer bills.
-
-
tags
JSON array that specifies key-value pairs for tags to attach to the customer. Each customer can be assigned a maximum of 20 tags.
-
keyrequired
Tag key
-
valuerequired
Tag value
-
Response Code | Description |
---|---|
201 OK |
Operation was successful |
422 Unprocessable Entity |
Unprocessable entity |
401 Unauthorized |
Unauthorized entry |
422 Unprocessable Entry |
Input format errors |
500 Internal Service Error |
Internal service error |
{
"name":"abc company",
"azure_customer_id":"34fdg",
"classification":"managed_with_access",
"trial_expiration_date":"date",
"billing_contact":"abc",
"partner_billing_configuration":{
"enabled":true,
"folder":"",
}
"tags": [{
"key": "customer_id", "value": "973532"
},
{
"key": "service_package", "value": "basic_managed"
}]
}
{
"name": "Acme Corp",
"classification": "managed_without_access",
"billing_contact": "john.doe@acmecorp.com",
"trial_expiration_date": "2016-09-22T00:00:00Z",
"partner_billing_configuration": {
"enabled": "true",
"folder": ""
},
"address": {
"street1": "1 Main St",
"city": "Springfield",
"state": "MA",
"zipcode": "01234",
"country": "US"
},
"tags": [{
"key": "customer_id", "value": "973532"
},
{
"key": "service_package", "value": "basic_managed"
}]
}
{
"id": 3947,
"name": "Acme Corp",
"classification": "managed_without_access",
"billing_contact": "john.doe@acmecorp.com",
"margin_percentage": 0.0,
"created_at": "2016-09-15T18:17:04Z",
"updated_at": "2016-09-15T18:17:04Z",
"generated_external_id": "1a2b3c4d5e6f",
"partner_billing_configuration": {
"enabled": true,
"folder": ""
},
"address": {
"street1": "1 Main St",
"city": "Springfield",
"state": "MA",
"zipcode": "01234",
"country": "US"
},
"tags": [{
"key": "customer_id", "value": "973532"
},
{
"key": "service_package", "value": "basic_managed"
}
],
"_links": {
"self": {
"href": "/v1/customers/3947"
}
}
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name":"abc company",
"azure_customer_id":"34fdg",
"classification":"managed_with_access",
"trial_expiration_date":"date",
"billing_contact":"abc",
"partner_billing_configuration":{
"enabled":true,
"folder":"",
}
"tags": [{
"key": "customer_id", "value": "973532"
},
{
"key": "service_package", "value": "basic_managed"
}]
}'
'https://chapi.cloudhealthtech.com/v2/customers'
Get All Partner Customers
Retrieve a list of all customer tenants that you have created in the CloudHealth Platform. This information is retrieved from the CloudHealth Platform. This endpoint can be used for both AWS and Azure customer tenants.
https://chapi.cloudhealthtech.com/v2/customers
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v2/customers'
Get Single Partner Customer
Retrieve a specific customer tenant that you have created in the CloudHealth Platform. This information is retrieved from the CloudHealth Platform. This endpoint can be used for both AWS and Azure customer tenants.
https://chapi.cloudhealthtech.com/v2/customers/:client_api_id
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v2/customers/<client_api_id>'
Modify Existing Partner Customer
Modify a partner customer tenant that already exists in the CloudHealth Platform. This endpoint can be used for both AWS and Azure customer tenants.
https://chapi.cloudhealthtech.com/v2/customers/:client_api_id
{
"name": "Acme Corporation",
"classification": "managed_with_access"
}
{
"id": XXXX,
"name": "Acme Corporation",
"classification": "managed_with_access",
"billing_contact": "john.doe@acmecorp.com",
"margin_percentage": 0.0,
"created_at": "2016-09-15T13:10:47Z",
"updated_at": "2016-09-15T16:46:34Z",
"generated_external_id": "1a2b3c4d5e6f",
"partner_billing_configuration": {
"enabled": true,
"folder": ""
},
"address": {
"street1": "1 Main St",
"street2": "",
"city": "Springfield",
"State": "MA",
"zipcode": "01234",
"Country": "US"
},
"_links": {
"self": {
"href": "/v1/customers/XXXX"
}
}
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"name": "Acme Corporation",
"classification": "managed_with_access"
}'
'https://chapi.cloudhealthtech.com/v2/customers/<client_api_id>'
Get All CSP Partner Customers
Retrieve a list of all customer tenants. This information is retrieved from the Azure Portal.
https://chapi.cloudhealthtech.com/v1/azure_partner_customers
Response Code | Description |
---|---|
200 OK |
Operation was successful |
401 Unauthorized |
Unauthorized entry |
500 Internal Service Error |
Internal service error |
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/azure_partner_customers'
Get Single CSP Partner Customer
Retrieve a specific customer tenant. This information is retrieved from the Azure Portal.
https://chapi.cloudhealthtech.com/v1/azure_partner_customers/:db_partner_customer_id
Response Code | Description |
---|---|
200 OK |
Operation was successful |
401 Unauthorized |
Unauthorized entry |
404 Not Found |
Entity not found |
500 Internal Service Error |
Internal service error |
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/azure_partner_customers/<db_partner_customer_id>'
Add Subscriptions to MSP Client
Assign subscriptions to a MSP client.
https://chapi.cloudhealthtech.com/v1/azure_subscriptions/add/db_msp_client_id
Response Code | Description |
---|---|
401 |
API key is wront or the request is not made by the partner |
500 |
Internal server error |
422 |
Azure ID is not found or is invalid or already assigned to a MSP client |
404 |
MSP client ID not found |
403 |
API key provided is invalid |
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/azure_subscriptions/add/db_msp_client_id'
Get all MSP Client Subscriptions
List all subscriptions associated with MSP clients.
https://chapi.cloudhealthtech.com/v1/azure_subscriptions/list/db_msp_client_id
Response Code | Description |
---|---|
401 |
API key is wront or the request is not made by the partner |
500 |
Internal server error |
422 |
Azure ID is not found or is invalid or already assigned to a MSP client |
404 |
MSP client ID not found |
403 |
API key provided is invalid |
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/azure_subscriptions/list/db_msp_client_id'
Remove Subscription from MSP Client
Removes all subscriptions associated with a MSP client.
https://chapi.cloudhealthtech.com/v1/azure_subscriptions/remove/db_msp_client_id
Response Code | Description |
---|---|
401 |
API key is wront or the request is not made by the partner |
500 |
Internal server error |
422 |
Azure ID is not found or is invalid or already assigned to a MSP client |
404 |
MSP client ID not found |
403 |
API key provided is invalid |
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/azure_subscriptions/remove/db_msp_client_id'
Partner Azure Account Assignment
Introduction to Partner Azure Account Assignment API
An introduction to the Account Assignment API.
Use this API to administer Azure partner customer accounts that belong to CloudHealth Partners and to assign Azure partner customer accounts to Partner Customers for partner-generated billing purposes.
Create Azure Account Assignment
Assign Azure accounts to Partner Customers for partner-generated billing purposes.
/v1/azure_partner_customer_accounts/add/:client_api_id
Parameters
-
azure_customer_idsrequired
An array of the customer IDs of the assigned Azure customer accounts.
If the corresponding Azure account does not exist in the customer’s CloudHealth account, it is created. If there is an error associated with one Azure account, none of the accounts in the request are assigned.
Response Code | Description |
---|---|
207 OK |
Operation was successful but may contain error messages |
401 Unauthorized |
Unauthorized entry |
404 Not Found |
Bad endpoint |
422 Unprocessable Entity |
Unprocessable entity |
500 Internal Service Error |
General error |
{
"azure_customer_ids": ["ab123", "fgh345"]
}
"azure_partner_customer_accounts": [
{
"customer_tenant_name": "Azure Two",
"azure_partner_customer_account": {
"name": "Indigo Montoya Inc",
"domain": "chazureteam.onmicrosoft.com",
"azure_customer_id": "ab123"
"created_at": "2018-12-27T17:36:36Z",
"updated_at": "2019-04-26T20:49:59Z"
}
},
{
"http_status": 422
"error": "azure_customer_id not found"
"azure_customer_id": "fgh345"
}]
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
{
"azure_customer_ids": ["ab123", "fgh345"]
}
'https://chapi.cloudhealthtech.com/v1/azure_partner_customer_accounts/add/<client_api_id>'
Get All Azure Account Assignments
Retrieve a list of all Azure customer accounts assigned to a partner customer tenant.
/v1/azure_partner_customer_accounts/list
Response Code | Description |
---|---|
200 OK |
Operation was successful |
401 Unauthorized |
Unauthorized entry |
500 Internal Service Error |
General error |
"azure_partner_customer_accounts": [
{
"customer_tenant_name": "arriva"
"azure_partner_customer_account": {
"name":"abacus",
"domain": "abacus.onmicrosoft.com",
"azure_customer_id": "dfg234",
"created_at": "2018-12-27T17:36:36Z",
"updated_at": "2019-04-26T20:49:59Z"
}
},{
"customer_tenant_name":"arriva",
"azure_partner_customer_account":{
"name":"card technologies",
"domain":"card.onmicrosoft.com",
"azure_customer_id":"xof194",
"created_at": "2018-12-27T17:36:36Z",
"updated_at": "2019-04-26T20:49:59Z"
}
},{
"customer_tenant_name":"Acme Accounts Corp",
"azure_partner_customer_account":{
"name":"acme accounts 1",
"domain":"acmeaccounts.onmicrosoft.com",
"azure_customer_id":"rtq683",
"created_at": "2019-01-25T12:33:31Z",
"updated_at": "2019-05-01T15:32:11Z"
}
}]
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/azure_partner_customer_accounts/list'
Get Single Azure Account Assignment
Retrieve information on a single Azure account assignment.
/v1/azure_partner_customer_accounts/list/:client_api_id
Response Code | Description |
---|---|
200 OK |
Operation was successful |
401 Unauthorized |
Unauthorized entry |
500 Internal Service Error |
General error |
"azure_partner_customer_accounts":[{
"customer_tenant_name":"arriva",
"azure_partner_customer_account":{
"name":"abacus",
"domain":"abacus.onmicrosoft.com",
"azure_customer_id":"dfg234",
"created_at": "2018-12-27T17:36:36Z",
"updated_at": "2019-04-26T20:49:59Z"
}
},{
"customer_tenant_name":"arriva",
"azure_partner_customer_account":{
"name":"card technologies"
"domain":"card.onmicrosoft.com",
"azure_customer_id":"xof194",
"created_at": "2018-12-27T17:36:36Z",
"updated_at": "2019-04-26T20:49:59Z"
}
}]
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json'
'https://chapi.cloudhealthtech.com/v1/azure_partner_customer_accounts/list/<client_api_id>'
Delete Azure Account Assignment
Remove the relationship between an Azure customer account and the partner customer that it was assigned to.
/v1/azure_partner_customer_accounts/remove/:client_api_id
Parameters
-
azure_customer_idsrequired
An array of the customer IDs of the Azure customer accounts that should be removed from the partner customer tenant.
Response Code | Description |
---|---|
207 OK |
Operation was successful |
401 Unauthorized |
Unauthorized entry |
404 Not Found |
Bad endpoint |
422 Unprocessable Entity |
Unprocessable entity |
500 Internal Service Error |
General error |
{
"azure_customer_ids": ["ab123", "fgh345"]
}
“azure_partner_customer_accounts”:[{
"azure_partner_customer_account":{
"name":"arriva",
"domain":"arriva.onmicrosoft.com",
"azure_customer_id":"ab123",
"created_at": "2018-12-27T17:36:36Z",
"updated_at": "2019-04-26T20:49:59Z"
},
{"http_status": 422
"error": "azure_customer_id not found"
"azure_customer_id": "fgh345"
}
}]
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
{
"azure_customer_ids": ["ab123", "fgh345"]
}
'https://chapi.cloudhealthtech.com/v1/azure_partner_customer_accounts/remove/<client_api_id>'
GCP Billing Accounts
Introduction to GCP Billing Account API
An introduction to the GCP Billing Account API.
The GCP billing account contains a customer’s projects and are the source of truth for a customer’s cost and usage data. By connecting the GCP billing account to the CloudHealth Platform, you allow the CloudHealth Platform access to the data the Platform needs to create reports and recommendations on how to better manage your cloud and cut down on costs. When the GCP billing account is connected, the Platform automatically pulls in derived projects. Random change.
The GCP Billing Account API allows both direct customers and GCP partners to connect GCP billing accounts with the CloudHealth Platform.
How to Get Client API ID
If you are a GCP partner, you need to include an additional parameter, the client_api_id
, with each request. CloudHealth generates a unique ID for each partner customer.
You can get the Client API ID for a customer using the Get All Customers endpoint. You can get the Client API ID for a customer from the CloudHealth Platform. From the left menu, select Partner > Customer > List. If the Client API Id column is not visible in the report, add it by clicking the Edit Columns button.
How to Get CloudHealth Billing Account ID
In order to use some of the GCP Billing Account endpoints, you need to provide the cloudhealth_billing_account_id
. CloudHealth generates a unique ID for each billing account.
You can get the CloudHealth Billing Account ID for a billing account from the CloudHealth Platform. From the left menu, go to Setup > Accounts > GCP Billing and open the billing account. The CloudHealth Billing Account ID of the partner customer appears in the browser URL. Here’s an example URL:
https://apps.cloudhealthtech.com/gcp_billing_accounts/5XXXXXXXXXX25
Here, 5XXXXXXXXXX25
is the CloudHealth Billing Account ID.
The CloudHealth Billing Account ID can also be retrieved using the Get All GCP Billing Accounts endpoint.
How to Encode a JSON Private Key
Several GCP Billing Account API endpoints require you to enter the JSON private key for the service account associated with the billing account. Before you can enter the JSON private key in the endpoint parameter, you must first encode the JSON private key.
- Create and download the JSON private key in gcloud. For more information, see the Creating and Managing Service Account Keys.
- In gcloud, enter the command
cloudshell download <private key name>.json
to download the JSON private key. When prompted, clickDownload
. - In Terminal, enter the command
cd downloads
to open the Downloads folder. - In Terminal, enter the following command to encode the downloaded private key:
base64 < '<private key name>.json'
- Copy the private key generated in the response. Use this private key for the
billing_account_service_account_json_key
orlinked_projects_json_key
parameter.
Enable GCP Billing Account
Enable a GCP billing account for a direct customer or a partner customer in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts
Parameters
-
client_api_id
The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.
-
billing_account_namerequired
String that specifies the unique display name of the customer’s billing account.
-
billing_account_idrequired
The GCP billing account ID of the billing account in the Google Console.
-
bq_billing_datasetrequired
String that specifies the BigQuery billing dataset name.
-
bq_billing_projectrequired
String that specifies the BigQuery billing project ID.
-
bq_activation_daterequired
Date in
YYYY-MM-DD
format that specifies the BigQuery activation date. To locate the activation date, run the following query in the BigQuery Query Editor, replacinginsert_table_name
with the BigQuery table name -SELECT min(export_time) FROM insert_table_name
. -
bq_billing_table
String that specifies the name of the BigQuery billing table. By default, the customer-owned BigQuery table is used. If you are a partner enabling a partner customer GCP billing account, you should assign the partner-owned BigQuery table, not the customer-owned table.
-
billing_bucketrequired
String that specifies the name of the billing bucket that contains the GCP billing export for the billing account.
-
billing_bucket_prefixrequired
String that specifies the report prefix for the billing bucket.
-
billing_account_service_accountrequired
String that specifies the GCP service account associated with the billing account.
-
billing_account_service_account_json_key
Enter the service account’s private JSON key in the format
data:application/json;base64, <private JSON key>
. -
linked_projects_service_account
String that specifies the second GCP service account associated with the billing account, if applicable. To ensure that the minimum set of permissions are used, some customers might prefer to use two service accounts for CloudHealth, one for billing data and one for asset and rightsizing data. CloudHealth recommends that partners use two service accounts for their partner customers, with the billing data service account owned by the partner and the asset and rightsizing data service account owned by the partner customer.
-
linked_projects_json_key
Enter the second service account’s private JSON key in the format
data:application/json;base64, <private JSON key>
.
Note: If you update the service account key here, it will not be applied to the derived projects. Use the Graphql API Update GCP Project Details to apply the service account key to all the derived projects.
Response Code | Description |
---|---|
422 Unprocessable Entity |
Unprocessable entity |
401 Unauthorized |
Unauthorized entry |
403 Forbidden |
Invalid Client API ID |
422 Unprocessable Entry |
Input format errors |
500 Internal Service Error |
Internal service error |
{
"billing_account_name": <billing_account_name>,
"billing_account_id": <billing_account_id>,
"bq_billing_dataset": <bq_billing_dataset>,
"bq_billing_project": <bq_billing_project>,
"bq_billing_activation_date": <bq_billing_activation_date>,
"billing_bucket": <billing_bucket>,
"billing_bucket_prefix": <billing_bucket_prefix>,
"billing_account_service_account": <billing_account_service_account>,
"billing_account_service_account_json_key": data:application/json;base64, <private JSON key>,
"linked_projects_service_account" : <linked_projects_service_account>,
"linked_projects_json_key": data:application/json;base64, <private JSON key>
}
{
"cloudhealth_billing_account_id": "6116033430514",
"billing_account_name": "Chayan Test BA",
"billing_account_id": "00807B-DFFF5B-2DAAB8",
}
curl --request POST -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"billing_account_name": <billing_account_name>,
"billing_account_id": <billing_account_id>,
"bq_billing_dataset": <bq_billing_dataset>,
"bq_billing_project": <bq_billing_project>,
"bq_billing_activation_date": <bq_billing_activation_date>,
"billing_bucket": <billing_bucket>,
"billing_bucket_prefix": <billing_bucket_prefix>,
"billing_account_service_account": <billing_account_service_account>,
"billing_account_service_account_json_key": <billing_account_service_account_json_key>,
"linked_projects_service_account" : <linked_projects_service_account>,
"linked_projects_json_key": <linked_projects_json_key>
}'
'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts'
Get All GCP Billing Accounts
Retrieve a list of all GCP billing accounts that have been enabled with the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts
Parameters
-
client_api_id
The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.
-
per_page
Specify how many results should be displayed per page. Default value is 25. Maximum value is 50.
-
page
Specify the page number for results. Default value is 1.
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts?per_page=<max_page_count>&page=<page_number>'
Get Single GCP Billing Account
Retrieve a specific GCP billing account that you have enabled with the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/:cloudhealth_billing_account_id
Parameters
-
cloudhealth_billing_account_idrequired
The CloudHealth billing account ID of the GCP billing account. For more information, see How to Get CloudHealth Billing Account ID.
-
client_api_id
The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.
curl --request GET -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/<cloudhealth_billing_account_id>'
Modify Existing GCP Billing Account
Modify a GCP billing account that already exists in the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/:cloudhealth_billing_account_id
Parameters
-
cloudhealth_billing_account_idrequired
The CloudHealth billing account ID of the GCP billing account. For more information, see How to Get CloudHealth Billing Account ID.
-
client_api_id
The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.
-
billing_account_name
String that specifies the unique display name of the customer’s billing account.
-
billing_account_id
The GCP billing account ID of the billing account in the Google Console.
-
bq_billing_dataset
String that specifies the BigQuery billing dataset name.
-
bq_billing_project
String that specifies the BigQuery billing project ID.
-
bq_activation_date
Date in
YYYY-MM-DD
format that specifies the BigQuery activation date. To locate the activation date, run the following query in the BigQuery Query Editor, replacinginsert_table_name
with the BigQuery table name -SELECT min(export_time) FROM insert_table_name
-
bq_billing_table
String that specifies the name of the BigQuery billing table.
-
billing_bucket
String that specifies the name of the billing bucket that contains the GCP billing export for the billing account.
-
billing_bucket_prefix
String that specifies the report prefix for the billing bucket.
-
billing_account_service_account
String that specifies the GCP service account associated with the billing account.
-
billing_account_service_account_json_key
Enter the service account’s private JSON key in the format
data:application/json;base64, <private JSON key>
. -
linked_projects_json_key
Enter the second service account’s private JSON key in the format
data:application/json;base64, <private JSON key>
.
Note: If you update the service account key here, it will not be applied to the derived projects. Contact CloudHealth Support to apply the service account key to all the derived projects.
{
"cloudhealth_billing_account_id": <cloudhealth_billing_account_id>,
"client_api_id": <client_api-id>,
"billing_account_name": <billing_account_name>,
"billing_account_id": <billing_account_id>,
"bq_billing_dataset": <bq_billing_dataset>,
"bq_billing_project": <bq_billing_project>,
"bq_billing_activation_date": <bq_billing_activation_date>,
"bq_billing_table": <bq_billing_table>,
}
{
"cloudhealth_billing_account_id": "6116033430514",
"billing_account_name": "Chayan Development BA",
"billing_account_id": "00807B-DFFF5B-2DAAB8",
}
curl --request PUT -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'{
"cloudhealth_billing_account_id": <cloudhealth_billing_account_id>,
"client_api_id": <client_api-id>,
"billing_account_name": <billing_account_name>,
"billing_account_id": <billing_account_id>,
"bq_billing_dataset": <bq_billing_dataset>,
"bq_billing_project": <bq_billing_project>,
"bq_billing_activation_date": <bq_billing_activation_date>,
"bq_billing_table": <bq_billing_table>,
}'
'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/<cloudhealth_billing_account_id>'
Delete GCP Billing Account
Remove a GCP billing account from the CloudHealth Platform.
https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/:cloudhealth_billing_account_id
Parameters
-
cloudhealth_billing_account_idrequired
The CloudHealth billing account ID of the GCP billing account. For more information, see How to Get CloudHealth Billing Account ID.
-
client_api_id
The client API ID of the partner customer whose billing account is being added. Required for partners configuring a partner customer’s billing account.
{
"cloudhealth_billing_account_id": "6116033430514",
"billing_account_name": "Chayan Test BA",
"billing_account_id": "00807B-DFFF5B-2DAAB8",
}
curl --request DELETE -H 'Authorization: Bearer <your_api_key>' -H 'Content-Type: application/json' -d
'https://chapi.cloudhealthtech.com/v1/gcp_billing_accounts/<cloudhealth_billing_account_id>'