Operations API - Temporal Cloud feature guide

Support, stability, and dependency info

• Temporal Cloud Operations API is in Public Preview for Temporal Cloud.

The Temporal Cloud Operations API (Cloud Ops API) is a library for managing the automation of Users, Namespaces, and Temporal Cloud Accounts.

Cloud Ops API is an open-source, public gRPC API, library to compile and generate code in your desired programming language.

Overview

You can manage Temporal Cloud resources programmatically using the Cloud Operations API, complementing the Temporal Cloud CLI (tcld). The Cloud Ops API, streamlines the automation of User, Namespace, and Account management tasks. Utilize gRPC protos, which compile into any language, for flexible integration. Authenticate using Temporal Cloud API Keys; for key management details, refer to the API Keys documentation.

Get started

Begin by ensuring your registration as a Temporal Cloud user. If you're not yet a user, sign up here.

Explore API functionalities through Go language samples showcasing Cloud Ops API usage.

Prerequisites:

This process assumes you have basic familiarity with gRPC and Protocol Buffers (protobuf).

• Temporal Cloud user account
• API Key for authentication
• Protocol Buffers
• gRPC in your preferred programming language

Compile the API

Download the gRPC protobufs from the Cloud Ops API repository.

Use gRPC to compile and generate code in your preferred programming language.

1. Clone the Temporal Cloud API repository:

   git clone https://github.com/temporalio/api-cloud.git
   cd api-cloud

2. Copy Protobuf files:

   • Navigate to the temporal directory.
   • Copy the protobuf files to your project directory.

3. Compile the Protobuf files:

   note

   Python requires gRPC tools to be installed.

   1. The following is an example of how to use the generated code for Python; however, this approach can be adapted for other supported programming languages:

   python -m grpc_tools.protoc -I./ --python_out=./ --grpc_python_out=./ *.proto
   • -I specifies the directory of the .proto files.
   • --python_out= sets the output directory for generated Python classes.
   • --grpc_python_out= sets the output directory for generated gRPC service classes.
   • *.proto processes all .proto files.

Use the generated code

After compiling the Protobuf files, you will have generated code files in your project directory. These files enable interaction with the Temporal Cloud API in your chosen programming language.

The following is an example of how to use the generated code for Python; however, this approach can be adapted for other programming languages:

1. Import the Generated Files:

   • Locate the Python files (.py) generated in your project directory.
   • Import these files into your Python application where you intend to interact with the Temporal Cloud API.

2. Utilize the API:

   • Use the classes and methods defined in the imported files to communicate with the Temporal Cloud services.
   • Ensure to handle any required authentication or configuration as needed for Temporal Cloud.

This approach can be adapted for other programming languages by following their respective import and usage conventions for the generated code files.

Use the API

When interacting with the Temporal Cloud Ops API, follow these guidelines:

1. API Version Header:

   • Always include the temporal-cloud-api-version header in your requests, specifying the API version identifier.
   • The current API version can be found here.

2. Connection URL:

   • Connect to the Temporal Cloud using the gRPC URL: saas-api.tmprl.cloud:443.

3. Engagement Steps:

   • Generate API Key:
     • Obtain an API Key for authentication. Note that many operations may require Admin privileges.
   • Set Up Client:
     • Establish a secure connection to the Temporal Cloud. Refer to the example Client setup in Go for guidance.
   • Execute Operations:
     • For operation specifics, refer to the cloudservice/v1/request_response.proto for gRPC messages and cloudservice/v1/service.proto for gRPC services.

These steps provide a structured approach to utilizing the Temporal Cloud Ops API effectively, ensuring proper authentication and connection setup.

Provide feedback

Your input is valuable. While the Temporal Cloud Ops API is in a Public Preview release status, we welcome your feedback.

You can provide feedback through the following channels:

• Submit request or feedback through a ZenDesk ticket
• Open an issue in the GitHub Repo