Read a report's data

After App Optimize API creates a report, you fetch the report's cost and utilization data. This operation downloads this information as columns and rows, structured according to the dimensions and metrics you specified when you requested your report.

This API request is different from getting a report's metadata, which only returns the report's configuration settings.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. To initialize the gcloud CLI, run the following command: 

    gcloud init

  5. Verify that you have the permissions required to complete this guide.

  6. Install the Google Cloud CLI.

  7. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  8. To initialize the gcloud CLI, run the following command: 

    gcloud init

  9. Verify that you have the permissions required to complete this guide.

Required roles

To get the permissions that you need to read a report's data, ask your administrator to grant you the App Optimize Viewer (roles/appoptimize.viewer) IAM role on the project that owns the report resource. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Read report data

To read data from a completed report, using the REST API, send a HTTP POST request to the report's :read endpoint.

  1. Use the following curl command to read the first page of report data:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"pageSize": PAGE_SIZE}' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports/REPORT_ID:read"

    Replace the following:

    • PROJECT_ID: the ID of the Google Cloud project that owns the report resource that you want to read.
    • REPORT_ID: the ID of the report to read. This ID was specified when the report was created, and can be obtained by listing reports.
    • PAGE_SIZE: the maximum number of rows to return per page. The server returns a maximum of 1,000 rows per page, even if you specify a larger value. Responses are also subject to a 10 MB size limit, so fewer rows might be returned to stay within that limit. If pageSize is omitted, a default size is used.

  2. If the request is successful, the API returns a JSON response containing the report schema and rows. Here's an example successful response:

    {
  "rows": [
    [
      "//apphub.googleapis.com/projects/123456789/locations/us-central1/applications/my-app-1",
      {
        "currency_code": "USD",
        "units": "106",
        "nanos": 321590000
      }
    ],
    [
      "//apphub.googleapis.com/projects/123456789/locations/us-central1/applications/my-app-2",
      {
        "currency_code": "USD",
        "units": "797",
        "nanos": 641691000
      }
    ]
  ],
  "columns": [
    {
      "name": "application",
      "type": "STRING"
    },
    {
      "name": "cost",
      "type": "RECORD",
      "columns": [
        {
          "name": "currency_code",
          "type": "STRING"
        },
        {
          "name": "units",
          "type": "INT64"
        },
        {
          "name": "nanos",
          "type": "INT64"
        }
      ]
    }
  ],
  "nextPageToken": "AABBCCddeeffGGHHiiJJkkLL"
}

    To understand the values in the cost field, see Interpreting cost metrics. For more information on the data and to understand its limitations, see Understanding the data.

  3. If the response includes a nextPageToken field, the report contains additional rows. To retrieve the next page of results, make another POST request that includes this token in the pageToken field of the JSON body:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"pageToken": "NEXT_PAGE_TOKEN", "pageSize": PAGE_SIZE}' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports/REPORT_ID:read"

    Replace the following:

    • NEXT_PAGE_TOKEN: the value of the nextPageToken received in the previous response.
    • PAGE_SIZE: the maximum number of rows to return per page. While you can change this value between page requests, the server-side limits still apply.

    Repeat this process until the response no longer contains a nextPageToken, indicating that you have retrieved all report data.

What's next