Getting Started with the Service Control API

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

Initial setup

The Service Control API works with managed services. To use the Service Control API, you need to first create a managed service using the Service Management API. For more information, see Service Management Getting Started.

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

  1. Visit Google Cloud Platform Console and select the project that your managed service belongs to.
  2. In the Google Cloud Platform Console, enable the 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. The following examples assume the file path is ~/credentials.json.
  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 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 managed 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"
}

After you have completed the preceding 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.
Was this page helpful? Let us know how we did: