Ansys Instance Management gRPC API

1.1.3 · active · verified Thu Apr 16

This library provides the autogenerated Python gRPC interface for the Ansys Platform Instance Management service. It allows Python applications to interact with the Ansys Platform to manage instances of Ansys products and services. The current version is 1.1.3, and it follows a release cadence tied to updates in the underlying gRPC API definition.

Common errors

```
ImportError: cannot import name 'instance_management_pb2' from 'ansys.api.platform.instancemanagement.v1'
```
cause This usually indicates an issue with how the package was installed, a corrupted environment, or an attempt to import a symbol that doesn't exist or is nested differently than expected.

fix Verify the installation (`pip check ansys-api-platform-instancemanagement`). Ensure the package is installed in the active environment. Reinstall the package if necessary: `pip install --upgrade ansys-api-platform-instancemanagement`.
```
grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with status Code.UNAUTHENTICATED>
```
cause The gRPC server rejected the request due to missing or invalid authentication credentials. This is common when trying to connect to a secure Ansys Platform service without providing an API key or JWT.

fix Provide valid call credentials using `grpc.composite_channel_credentials` or similar. For example, include an API token as metadata in the gRPC call.
```
TypeError: Parameter to MergeFrom() must be instance of same class: expected instance_management_pb2.ListInstancesRequest got instance_management_pb2.ListInstancesRequest
```
cause This cryptic error often occurs in gRPC/Protobuf when different versions of `protobuf` or the generated `.pb2` files are loaded into the same Python interpreter, leading to type mismatches even if the class names appear identical. It can also happen with mixed `grpcio` and `protobuf` versions.

fix Ensure `grpcio` and `protobuf` are installed from a consistent source and are compatible. Isolate your environment (e.g., using `venv`), and try reinstalling all related packages: `pip uninstall -y ansys-api-platform-instancemanagement grpcio protobuf && pip install ansys-api-platform-instancemanagement`.

Warnings

gotcha Direct modification of the generated `_pb2` and `_pb2_grpc` files is strongly discouraged. Any changes will be overwritten in subsequent updates or regeneration processes, leading to unexpected behavior.
Fix: Interact with the gRPC API solely through the provided Python client stub and message classes without modifying their source files.
breaking The `protobuf` library dependency was updated in v1.1.0 to require `protobuf>=3.19,<6`. If you have an older `protobuf` version (e.g., <3.19) installed, it might cause compatibility issues or `TypeError` exceptions during message serialization/deserialization.
Fix: Ensure your `protobuf` version is within the specified range by running `pip install --upgrade protobuf` or installing a compatible version alongside `ansys-api-platform-instancemanagement`.
gotcha Using `grpc.insecure_channel` is suitable only for local development or trusted network environments. Production deployments require secure channels (`grpc.secure_channel`) with appropriate TLS/SSL certificates and often API-key or token-based authentication.
Fix: For production, use `grpc.secure_channel` and provide `grpc.ssl_channel_credentials()` along with `grpc.access_token_call_credentials()` or other `grpc.composite_call_credentials()` as required by your Ansys Platform setup.

Install

pip install ansys-api-platform-instancemanagement Install stable version

Imports

instance_management_pb2

from ansys.api.platform.instancemanagement.v1 import instance_management_pb2

InstanceManagementServiceStub

from ansys.api.platform.instancemanagement.v1 import instance_management_pb2_grpc

grpc
wrong:
```
from grpc import channel # Or other specific imports unless needed
```
correct:
```
import grpc
```
Import `grpc` directly for common operations like channel creation.

Quickstart

This quickstart demonstrates how to establish an insecure gRPC connection to a local Ansys Platform Instance Management service endpoint and call the `ListInstances` method. For production environments, secure channels (e.g., `grpc.secure_channel`) and robust authentication (e.g., API keys, JWT tokens via call credentials) are mandatory. The `GRPC_TARGET` can be configured via an environment variable.

import grpc
import os
from ansys.api.platform.instancemanagement.v1 import instance_management_pb2_grpc
from ansys.api.platform.instancemanagement.v1 import instance_management_pb2

# For local testing without authentication
# For production, use secure channels and proper authentication (e.g., API key, JWT).
# Example with an insecure channel, replace with your gRPC endpoint.
GRPC_TARGET = os.environ.get('ANSYS_PLATFORM_GRPC_TARGET', 'localhost:50051')

try:
    # Establish a gRPC channel
    channel = grpc.insecure_channel(GRPC_TARGET)

    # Create a gRPC client stub
    client = instance_management_pb2_grpc.InstanceManagementServiceStub(channel)

    # Call a sample method (e.g., ListInstances)
    # Note: This operation might require specific permissions or an actual running service
    #       that supports insecure connections or has no instances to list.
    request = instance_management_pb2.ListInstancesRequest()
    response = client.ListInstances(request)

    print(f"Successfully called ListInstances. Found {len(response.instances)} instances.")
    for instance in response.instances:
        print(f"  - Instance ID: {instance.id}, Name: {instance.name}, State: {instance.state}")

except grpc.RpcError as e:
    print(f"gRPC Error: {e.code()} - {e.details()}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    if 'channel' in locals() and channel:
        channel.close()

view raw JSON →