working version

Max Wang · Max Wang · commit 2ec1de2f2600 · 2025-08-28T16:02:00.000-07:00
diff --git a/README.md b/README.md
@@ -6,13 +6,15 @@ A minimal Python SDK to use Microsoft Dataverse as a database for Azure AI Found
 - OData CRUD — Thin wrappers over Dataverse Web API (create/get/update/delete).
 - Metadata helpers — Create/inspect/delete simple custom tables (EntityDefinitions + Attributes).
 - Pandas helpers — Convenience DataFrame oriented wrappers for quick prototyping/notebooks.
+- Custom API — CRUD for Custom API that wraps over Dataverse Web API
 - Auth — Azure Identity (`TokenCredential`) injection.
 
 ## Features
 
 - Simple `DataverseClient` facade for CRUD, SQL (read-only), and table metadata.
 - SQL-over-API: T-SQL routed through Custom API endpoint (no ODBC / TDS driver required).
 - Table metadata ops: create simple custom tables with primitive columns (string/int/decimal/float/datetime/bool) and delete them.
+- Custom API support for CRUD and invoking
 - Optional pandas integration (`PandasODataClient`) for DataFrame based create / get / query.
 
 Auth:
@@ -139,7 +141,9 @@ Notes:
 - For CRUD methods that take a record id, pass the GUID string (36-char hyphenated). Parentheses around the GUID are accepted but not required.
 - SQL is routed through the Custom API named in `DataverseConfig.sql_api_name` (default: `McpExecuteSqlQuery`).
 
+### Custom API functionalities
 
+See `examples/quickstart_custom_api.py` for a Custom API workflow from create -> read- > call -> update -> delete.
 
 ### Pandas helpers
 
@@ -152,6 +156,7 @@ VS Code Tasks
 ## Limitations / Future Work
 - No batching, upsert, or association operations yet.
 - Minimal retry policy in library (network-error only); examples include additional backoff for transient Dataverse consistency.
+- Custom API SDK doesn't support adding service logic like Plug-in currently, so it can only function like business events.
 
 ## Contributing
 
diff --git a/examples/quickstart_custom_api.py b/examples/quickstart_custom_api.py
@@ -9,31 +9,31 @@
 if src_path not in sys.path:
     sys.path.insert(0, src_path)
 
-from dataverse_sdk import DataverseClient  # noqa: E402
-from azure.identity import InteractiveBrowserCredential  # noqa: E402
-
-"""Quickstart: Custom API lifecycle (create -> add params -> invoke -> update -> delete).
-
-Two operating modes:
-1. Plug-in backed (you supply PLUGIN_TYPENAME): request + response property, plug-in sets the output.
-2. Plug-in-less (business event style): ONLY a request parameter is created. Invocation will succeed
-    (HTTP 204 / empty body or {{}}) even though no plug-in logic runs. This matches docs stating a
-    custom API does not strictly require a plug-in (it can just raise events). In this mode we omit
-    response properties because without server logic they cannot be populated and may cause confusion.
-
-Below we auto-detect: if PLUGIN_TYPENAME is blank we skip creating the response property and use a
-simple string parameter value. If a plug-in name is provided we also create a response property.
-"""
+from dataverse_sdk import DataverseClient 
+from azure.identity import InteractiveBrowserCredential
 
 # ---------------- Configuration ----------------
 base_url = "https://aurorabapenv0f528.crm10.dynamics.com"  # <-- change to your environment
 CUSTOM_API_UNIQUE_NAME = "new_EchoMessage"     # Must be globally unique in the org
 REQUEST_PARAM_UNIQUE = "new_EchoMessage_Message"
 RESPONSE_PROP_UNIQUE = "new_EchoMessage_Response"
-CLEANUP = True  # Set True to delete the Custom API at the end
-PLUGIN_TYPENAME = ""  # e.g. "Contoso.Plugins.EchoMessagePlugin" (leave blank for plug-in-less mode)
-INCLUDE_RESPONSE_PROPERTY = bool(PLUGIN_TYPENAME)  # Only create a response property when a plug-in can populate it
 PUBLISH_STRATEGY = "auto"  # auto | skip | force. force = call PublishAllXml, auto = poll metadata first
+# Parameter type codes (subset): 10=String, 7=Int32, 6=Float. Using Int32 for this run.
+REQUEST_PARAMETERS = [{
+    "uniquename": REQUEST_PARAM_UNIQUE,
+    "name": "Message",
+    "displayname": "Message",
+    "type": 7,  # Int32
+    "description": "Integer value to echo / raise event with",
+    "isoptional": False,
+}]
+RESPONSE_PROPERTIES = [{
+    "uniquename": RESPONSE_PROP_UNIQUE,
+    "name": "ResponseMessage",
+    "displayname": "ResponseMessage",
+    "type": 10,  # String response
+    "description": "Echoed string",
+}]
 
 # ------------------------------------------------
 client = DataverseClient(base_url=base_url, credential=InteractiveBrowserCredential())
@@ -56,7 +56,7 @@ def backoff_retry(op, *, delays=(0, 2, 5), retry_http_statuses=(429, 500, 502, 5
             time.sleep(d)
         try:
             return op()
-        except Exception as ex:  # noqa: BLE001
+        except Exception as ex:
             last_exc = ex
             if isinstance(ex, requests.exceptions.HTTPError):
                 code = getattr(getattr(ex, "response", None), "status_code", None)
@@ -66,18 +66,16 @@ def backoff_retry(op, *, delays=(0, 2, 5), retry_http_statuses=(429, 500, 502, 5
     if last_exc:
         raise last_exc
 
-# 1) List existing custom APIs with our prefix for context
-print("List existing custom APIs (prefix=new_):")
+# 1) Check if target Custom API exists
+print("Check target Custom API existence:")
 try:
-    plan("odata.list_custom_apis(filter_expr=uniquename startswith 'new_')")
-    existing = backoff_retry(lambda: odata.list_custom_apis(filter_expr="startswith(uniquename,'new_')"))
-    print({"count": len(existing)})
-    for item in existing[:5]:  # show a few
-        print(" -", item.get("uniquename"), "isfunction=" + str(item.get("isfunction")))
-except Exception as e:  # noqa: BLE001
-    print(f"List custom APIs failed: {e}")
+    plan("odata.get_custom_api(unique_name)")
+    existing = backoff_retry(lambda: odata.get_custom_api(unique_name=CUSTOM_API_UNIQUE_NAME))
+    print({"exists": bool(existing)})
+except Exception as e:
+    print(f"Existence check failed: {e}")
 
-# 2) Create the Custom API if absent
+# 2) Create the Custom API, remove the existing one first if present
 print("Recreate Custom API fresh (delete if exists then create):")
 existing_api = odata.get_custom_api(unique_name=CUSTOM_API_UNIQUE_NAME)
 if existing_api:
@@ -87,40 +85,30 @@ def backoff_retry(op, *, delays=(0, 2, 5), retry_http_statuses=(429, 500, 502, 5
         print({"deleted_prior": True})
         # Brief pause to allow backend cleanup
         time.sleep(2)
-    except Exception as del_ex:  # noqa: BLE001
+    except Exception as del_ex:
         print({"delete_prior_error": str(del_ex)})
 
-plan("odata.create_custom_api (inline request parameter + optional response property)")
+plan("odata.create_custom_api (inline request parameter + response property)")
 try:
-    # Parameter type codes (subset): 10=String, 7=Integer, 6=Float. We use String for plug-in-less clarity.
-    request_parameters = [{
-        "uniquename": REQUEST_PARAM_UNIQUE,
-        "name": "Message",
-        "displayname": "Message",
-        "type": 6,  # Int32 (common & simple)
-        "description": "Integer message to echo / raise event with",
-        "isoptional": False,
-    }]
-    response_properties = []
-    if INCLUDE_RESPONSE_PROPERTY:
-        response_properties.append({
-            "uniquename": RESPONSE_PROP_UNIQUE,
-            "name": "ResponseMessage",
-            "displayname": "ResponseMessage",
-            "type": 6,  # Int32 response
-            "description": "Echoed integer (set by plug-in)",
-        })
-
     api_meta = backoff_retry(lambda: odata.create_custom_api(
         unique_name=CUSTOM_API_UNIQUE_NAME,
         name="Echo Message",
         description="Echo sample (metadata only) created by SDK quickstart.",
         is_function=False,
         binding_type="Global",
-        request_parameters=request_parameters,
-        response_properties=response_properties,
+        request_parameters=REQUEST_PARAMETERS,
+        response_properties=RESPONSE_PROPERTIES,
     ))
-    print({"created": True, "customapiid": api_meta.get("customapiid")})
+    print({
+        "created": True,
+        "message": "Created Custom API with the following parameters",
+        "unique_name": CUSTOM_API_UNIQUE_NAME,
+        "customapiid": api_meta.get("customapiid"),
+        "description": "Echo sample (metadata only) created by SDK quickstart.",
+        "is_function": False,
+        "request_parameters": [p.get("name") for p in REQUEST_PARAMETERS],
+        "response_properties": [p.get("name") for p in RESPONSE_PROPERTIES]
+    })
 except Exception as e:
     print("Create Custom API failed:")
     traceback.print_exc()
@@ -131,19 +119,35 @@ def backoff_retry(op, *, delays=(0, 2, 5), retry_http_statuses=(429, 500, 502, 5
         except Exception:
             pass
     sys.exit(1)
-created_this_run = True
 
 customapiid = api_meta.get("customapiid") if api_meta else None
 if not customapiid:
     print("Missing customapiid; cannot continue")
     sys.exit(1)
 
+# 3) Read back the Custom API metadata just created
+print("Read Custom API metadata:")
+try:
+    plan("odata.get_custom_api(unique_name)")
+    read_back = backoff_retry(lambda: odata.get_custom_api(unique_name=CUSTOM_API_UNIQUE_NAME))
+    if read_back:
+        # Display a concise subset of fields
+        subset = {k: read_back.get(k) for k in [
+            "customapiid", "uniquename", "isfunction", "bindingtype", "allowedcustomprocessingsteptype", "isprivate", "executeprivilegename", "description"
+        ]}
+        subset["request_param_count"] = len(REQUEST_PARAMETERS)
+        subset["response_prop_count"] = len(RESPONSE_PROPERTIES)
+        print({"read_back": subset})
+    else:
+        print({"read_back": None})
+except Exception as e:
+    print({"read_custom_api_error": str(e)})
+
 # Publish customizations so the action metadata is available for invocation (required for freshly created APIs)
 print("Ensure custom API metadata is available:")
 
 def _action_in_metadata(action_name: str) -> bool:
     try:
-        # Must include auth headers; previously we overwrote them causing 401
         md_resp = odata._request(
             "get",
             f"{odata.api}/$metadata",
@@ -152,7 +156,7 @@ def _action_in_metadata(action_name: str) -> bool:
         if md_resp.status_code == 200:
             txt = md_resp.text
             return f"Name=\"{action_name}\"" in txt
-    except Exception:  # noqa: BLE001
+    except Exception:
         return False
     return False
 
@@ -197,108 +201,60 @@ def wait_for_action(action_name: str, timeout_sec: int = 60, interval: float = 2
                 print({"metadata_present_after_publish": False, "hint": "Invocation retry logic will attempt anyway."})
         except requests.exceptions.Timeout:
             print({"published": False, "error": "PublishAllXml timeout (15s)", "hint": "Proceeding; action may still become available."})
-        except Exception as pub_ex:  # noqa: BLE001
+        except Exception as pub_ex:
             print({"published": False, "error": str(pub_ex)})
 else:
     print({"publish_strategy": PUBLISH_STRATEGY, "warning": "Unknown strategy value"})
 
-# Optional: bind an existing plug-in type so invocation returns something meaningful.
-# Provide the fully-qualified class name in PLUGIN_TYPENAME above. The plug-in must
-# set OutputParameters["ResponseMessage"] (or whatever your response property name is).
-if PLUGIN_TYPENAME:
-    print("Attempt plug-in bind:")
-    try:
-        plan(f"lookup plugintype '{PLUGIN_TYPENAME}' then patch custom api")
-        # Lookup plugintypeid by typename
-        url = f"{odata.api}/plugintypes"
-        params = {"$select": "plugintypeid,typename", "$filter": f"typename eq '{PLUGIN_TYPENAME}'"}
-        r = odata._request("get", url, headers=odata._headers(), params=params)
-        r.raise_for_status()
-        vals = r.json().get("value", [])
-        if vals:
-            plugintypeid = vals[0]["plugintypeid"]
-            log_call("odata.update_custom_api (attach plugintype)")
-            patched = odata.update_custom_api(unique_name=CUSTOM_API_UNIQUE_NAME, changes={
-                "plugintypeid@odata.bind": f"/plugintypes({plugintypeid})"
-            })
-            print({"plugin_attached": True, "plugintypeid": plugintypeid})
-        else:
-            print({"plugin_attached": False, "reason": "Plugin typename not found"})
-    except Exception as ex:  # noqa: BLE001
-        resp = getattr(ex, 'response', None)
-        body = None
-        if resp is not None:
-            try:
-                body = resp.text[:800]
-            except Exception:  # noqa: BLE001
-                body = None
-        print({"plugin_attach_error": str(ex), "body": body})
-
-# 3) (Re)List parameters / response properties for visibility
-print("Parameters / Response Properties:")
+# 4) (Re)List parameters / response properties for visibility
+print("List Parameters / Response Properties:")
 try:
     params = odata.list_custom_api_request_parameters(customapiid)
     props = odata.list_custom_api_response_properties(customapiid)
     print({"parameters": [p.get("name") for p in params], "responses": [p.get("name") for p in props]})
-except Exception as e:  # noqa: BLE001
+except Exception as e:
     print(f"List params/props failed: {e}")
 
-# 4) Invoke the Custom API (will only succeed if backed by server logic)
+# 5) Invoke the Custom API
 print("Invoke Custom API:")
-time.sleep(1)
 try:
-    # Fetch $metadata to inspect the expected parameter names (diagnostic aid)
-    try:
-        meta_url = f"{odata.api}/$metadata"
-        md_resp = odata._request(
-            "get",
-            meta_url,
-            headers={**odata._headers(), "Accept": "application/xml"},
-        )
-        md_resp.raise_for_status()
-        md_text = md_resp.text
-        # Extract the Action definition snippet for debugging
-        snippet = None
-        idx = md_text.find(f"Name=\"{CUSTOM_API_UNIQUE_NAME}\"")
-        if idx != -1:
-            snippet = md_text[max(0, idx-200): idx+400]
-        if snippet:
-            print({"metadata_snippet": snippet.replace('\n', ' ')[:400]})
-    except Exception as md_ex:  # noqa: BLE001
-        print({"metadata_fetch_error": str(md_ex)})
-
-    base_message = 123  # Int matches parameter type 6
-    # Prefer the unique name first (proved to work in plug-in-less mode); keep logical name fallback for completeness
-    candidate_param_names = [REQUEST_PARAM_UNIQUE, "Message"]
+    base_message = 42  # Matches Int32 parameter type
+    candidate_param_names = [REQUEST_PARAM_UNIQUE]
     last_error = None
     for pname in candidate_param_names:
-        for attempt in range(1,4):  # up to 3 attempts each name for propagation
+        for attempt in range(1,4):  # up to 3 attempts each name for propagation / publish delay
             invoke_payload = {pname: base_message}
             plan(f"attempt {attempt} param '{pname}' -> odata.call_custom_api('{CUSTOM_API_UNIQUE_NAME}', {invoke_payload})")
             def invoke():
                 return odata.call_custom_api(CUSTOM_API_UNIQUE_NAME, invoke_payload)
             try:
                 result = invoke()
-                print({"invoked": True, "result": result, "mode": "plugin" if INCLUDE_RESPONSE_PROPERTY else "plugin-less", "used_param": pname, "attempt": attempt})
+                print({"invoked": True, "message": "note the None in new_EchoMessage_Response is expected as there is no server logic attached to the workflow", "result": result, "used_param": pname, "attempt": attempt})
                 raise SystemExit  # exit double loop cleanly
-            except requests.exceptions.HTTPError as ex:  # noqa: PERF203
+            except requests.exceptions.HTTPError as ex:
                 last_error = ex
                 resp = getattr(ex, 'response', None)
+                status = getattr(resp, 'status_code', None)
                 body = None
                 if resp is not None:
                     try:
-                        body = resp.text[:300]
-                    except Exception:  # noqa: BLE001
+                        body = resp.text[:600]
+                    except Exception:
                         body = None
-                if resp is not None and resp.status_code == 400 and "not a valid parameter" in (body or ""):
-                    # Wait and retry
+                body_lc = (body or "").lower()
+                # Handle not yet routable (sdkmessage) 404 specially
+                if status == 404 and 'sdkmessage' in body_lc:
+                    print({"retry": True, "reason": "404 sdkmessage not found (known issue where the custom api exists but metadata is not updated yet)", "attempt": attempt})
+                    time.sleep(2 + attempt)
+                    continue
+                if status == 400 and "not a valid parameter" in body_lc:
                     time.sleep(2 + attempt)
                     continue
-                if resp is not None and resp.status_code == 400 and "Int32" in (body or ""):
-                    print({"hint": "Server expects Int32; ensure payload is int (it is). If still failing, metadata not published yet."})
+                if status == 400 and "int32" in body_lc:
+                    print({"hint": "Server expects Int32; payload is int. Likely metadata publish delay."})
                     time.sleep(2)
                     continue
-                print({"attempt": pname, "error": str(ex), "body": body})
+                print({"attempt": pname, "error": str(ex), "status": status, "body": body})
                 time.sleep(2)
                 continue
     if last_error:
@@ -315,23 +271,20 @@ def invoke():
             body = None
     print({"invoked": False, "error": str(e), "body": body, "hint": "If 400, verify parameter Type code & payload match; for plug-in-less mode only request param should be present."})
 
-# 5) Update description (demonstrate patch)
-print("Update Custom API description:")
+# 6) Update custom api
+print("Update Custom API:")
 try:
     plan("odata.update_custom_api(unique_name, changes={'description': 'Updated via quickstart'})")
     updated = backoff_retry(lambda: odata.update_custom_api(unique_name=CUSTOM_API_UNIQUE_NAME, changes={"description": "Updated via quickstart"}))
     print({"updated": True, "description": updated.get("description")})
-except Exception as e:  # noqa: BLE001
+except Exception as e:
     print({"updated": False, "error": str(e)})
 
-# 6) Conditional cleanup
-if CLEANUP and created_this_run:
-    print("Cleanup: delete Custom API created in this run")
-    try:
-        plan("odata.delete_custom_api(unique_name)")
-        backoff_retry(lambda: odata.delete_custom_api(unique_name=CUSTOM_API_UNIQUE_NAME))
-        print({"deleted": True})
-    except Exception as e:  # noqa: BLE001
-        print({"deleted": False, "error": str(e)})
-else:
-    print({"cleanup": False, "reason": "CLEANUP flag False or pre-existing API"})
+# 7) Cleanup
+print("Cleanup: delete Custom API created in this run")
+try:
+    plan("odata.delete_custom_api(unique_name)")
+    backoff_retry(lambda: odata.delete_custom_api(unique_name=CUSTOM_API_UNIQUE_NAME))
+    print({"deleted": True})
+except Exception as e:
+    print({"deleted": False, "error": str(e)})
diff --git a/src/dataverse_sdk/odata.py b/src/dataverse_sdk/odata.py
