Getting Started

This page describes the basic steps necessary to set up the Google Service Control API on your local machine and test it using the curl command.

Initial setup

Google Service Control works with services managed by Google Service Management. To use Google Service Control, you need to first create a service using Google Service Management. See Service Management Getting Started for more information.

Once you have created a service, you need to complete the following steps before using the Google Service Control API from your service.

  1. Visit Google Cloud Console and select the project that your service belongs to.
  2. In the Cloud Console, enable the Google Service Control API for the project.
  3. Create a new service account for local testing, and download its JSON credential file to your local machine. We will assume the file path is ~/credentials.json in the following examples.
  4. Grant the roles/servicemanagement.serviceController role to the newly created service account. See Access Control for details.
  5. Install oauth2l on your local machine for interacting with the Google OAuth system.

Test with curl

  1. Verify your initial setup first:
oauth2l header --json ~/credentials.json cloud-platform
  1. If your initial setup is correct, you should see output like this:

    Authorization: Bearer y29.xxxxxxx
    
  2. Define a convenient shell alias for calling Google REST APIs:

alias gcurl='curl -H "$(oauth2l header --json ~/credentials.json cloud-platform userinfo.email)" -H "Content-Type: application/json" '

The following shell command sequence demonstrates the incremental steps to call the Google Service Control API.

# Call with invalid service name "invalid.com". For security and privacy
# reasons, the permission check typically happens before other checks.
$ gcurl -d '{}' https://servicecontrol.googleapis.com/v1/services/invalid.com:check
{
  "error": {
    "code": 403,
    "message": "Permission 'servicemanagement.services.check' denied on service 'invalid.com'.",
    "status": "PERMISSION_DENIED"
  }
}

# Call without proper permission on a service.
$ gcurl -d '{}' https://servicecontrol.googleapis.com/v1/services/servicecontrol.googleapis.com:check
{
  "error": {
    "code": 403,
    "message": "Permission 'servicemanagement.services.check' denied on service 'servicecontrol.googleapis.com'.",
    "status": "PERMISSION_DENIED"
  }
}

# Call with invalid request.
$ gcurl -d '{}' https://servicecontrol.googleapis.com/v1/services/endpointsapis.appspot.com:check
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}

# This and following call assume that the service, operation name and
# project being checked are "endpointsapis.appspot.com",
# "google.example.hello.v1.HelloService.GetHello" and
# "endpointsapis-consumer" correspondingly.
# Change to the name of your service, operation and project.
# Call with invalid request.
$ gcurl -d '{
  "operation": {
    "operationId": "123e4567-e89b-12d3-a456-426655440000",
    "consumerId": "project:endpointsapis-consumer",
    "startTime": "2016-06-12T22:00:15Z",
    "operationName": "google.example.hello.v1.HelloService.GetHello"
  }
}' https://servicecontrol.googleapis.com/v1/services/endpointsapis.appspot.com:check
{
  "checkErrors": [
  {
    "code": "SERVICE_NOT_ACTIVATED",
    "detail": "Service 'endpointsapis.appspot.com' is not enabled for consumer 'project:endpointsapis-consumer'."
  }
  ]
}

# Successful call to "services.check" method after the API is enabled for
# the project.
$ gcurl -d '{
  "operation": {
    "operationId": "123e4567-e89b-12d3-a456-426655440000",
    "consumerId": "project:endpointsapis-consumer",
    "startTime":"2016-07-31T05:20:00Z",
    "operationName":"google.example.hello.v1.HelloService.GetHello"
  }
}' https://servicecontrol.googleapis.com/v1/services/endpointsapis.appspot.com:check
{
  "operationId": "123e4567-e89b-12d3-a456-426655440000"
}

Once you have completed above the above steps:

  • You have a functional local test setup that you can use to call any Google Cloud Platform APIs.
  • You have a functional service that you can use with the Service Management API and the Service Control API.
  • You have a service account with correct permissions that you can use to run your service.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.