Ansys Instance Management gRPC API

1.1.3 verified Thu Apr 16 auth: no python

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.

pip install ansys-api-platform-instancemanagement

Common errors

error 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.

error 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.

error 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.

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()