{"id":8826,"library":"ansys-api-platform-instancemanagement","title":"Ansys Instance Management gRPC API","description":"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.","status":"active","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/ansys/ansys-api-platform-instancemanagement","tags":["ansys","grpc","api","autogenerated","platform","instance-management"],"install":[{"cmd":"pip install ansys-api-platform-instancemanagement","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for gRPC communication.","package":"grpcio","optional":false},{"reason":"Required for protobuf message serialization/deserialization.","package":"protobuf","optional":false}],"imports":[{"symbol":"instance_management_pb2","correct":"from ansys.api.platform.instancemanagement.v1 import instance_management_pb2"},{"symbol":"InstanceManagementServiceStub","correct":"from ansys.api.platform.instancemanagement.v1 import instance_management_pb2_grpc"},{"note":"Import `grpc` directly for common operations like channel creation.","wrong":"from grpc import channel # Or other specific imports unless needed","symbol":"grpc","correct":"import grpc"}],"quickstart":{"code":"import grpc\nimport os\nfrom ansys.api.platform.instancemanagement.v1 import instance_management_pb2_grpc\nfrom ansys.api.platform.instancemanagement.v1 import instance_management_pb2\n\n# For local testing without authentication\n# For production, use secure channels and proper authentication (e.g., API key, JWT).\n# Example with an insecure channel, replace with your gRPC endpoint.\nGRPC_TARGET = os.environ.get('ANSYS_PLATFORM_GRPC_TARGET', 'localhost:50051')\n\ntry:\n    # Establish a gRPC channel\n    channel = grpc.insecure_channel(GRPC_TARGET)\n\n    # Create a gRPC client stub\n    client = instance_management_pb2_grpc.InstanceManagementServiceStub(channel)\n\n    # Call a sample method (e.g., ListInstances)\n    # Note: This operation might require specific permissions or an actual running service\n    #       that supports insecure connections or has no instances to list.\n    request = instance_management_pb2.ListInstancesRequest()\n    response = client.ListInstances(request)\n\n    print(f\"Successfully called ListInstances. Found {len(response.instances)} instances.\")\n    for instance in response.instances:\n        print(f\"  - Instance ID: {instance.id}, Name: {instance.name}, State: {instance.state}\")\n\nexcept grpc.RpcError as e:\n    print(f\"gRPC Error: {e.code()} - {e.details()}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if 'channel' in locals() and channel:\n        channel.close()\n","lang":"python","description":"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."},"warnings":[{"fix":"Interact with the gRPC API solely through the provided Python client stub and message classes without modifying their source files.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"ImportError: cannot import name 'instance_management_pb2' from 'ansys.api.platform.instancemanagement.v1'"},{"fix":"Provide valid call credentials using `grpc.composite_channel_credentials` or similar. For example, include an API token as metadata in the gRPC call.","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.","error":"grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with status Code.UNAUTHENTICATED>"},{"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`.","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.","error":"TypeError: Parameter to MergeFrom() must be instance of same class: expected instance_management_pb2.ListInstancesRequest got instance_management_pb2.ListInstancesRequest"}]}