Automate with your own tools

​

Before you start

• An Owner has activated the Organization and set up the Environment in the app. Both happen once.
• Your tool calls the API with a workload identity that holds GV.APIContributor; see API authentication. The API reference lists every operation and its schema.
• Your tool makes the Fabric calls with an identity that has the Fabric access each step names: its own service principal, or the person it works for when an agent acts on someone’s behalf. A service principal also needs your Fabric administrator to let service principals use Fabric APIs.

​

Create Tables, a Table Pair, and Tests

curl --fail-with-body \
  --header "Authorization: Bearer ${gv_access_token}" \
  --header "Content-Type: application/json" \
  --data '{"name": "Orders", "workspace_id": "<workspace-id>", "lakehouse_id": "<lakehouse-id>", "path": "Tables/dbo/orders", "format": "delta"}' \
  "https://api.generalvalidation.com/api/v1/fabric/tables"

​

Give the workspace identity read access

curl --fail-with-body \
  --header "Authorization: Bearer ${gv_access_token}" \
  "https://api.generalvalidation.com/api/v1/fabric/pairs/<pair-id>/read-access"

{
  "identity_id": "<workspace-identity-object-id>",
  "workspaces": [
    {
      "workspace_id": "<source-workspace-id>",
      "workspace_role": "Viewer",
      "lakehouses": [
        {
          "lakehouse_id": "<lakehouse-id>",
          "data_access_role": "GeneralValidation1a2b3c4d",
          "paths": ["/Tables/dbo/orders"]
        }
      ]
    }
  ]
}

1. Add the identity as Viewer on the workspace with POST https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/roleAssignments and the body {"principal": {"id": "<identity_id>", "type": "ServicePrincipal"}, "role": "Viewer"}. A 409 response means the identity already has a role there; keep it.
2. For each Lakehouse, give the identity Read on the listed paths through a OneLake data access role. The app keeps them in the role named data_access_role, so add the paths there and both stay in one role. Fabric’s PUT .../items/<lakehouse-id>/dataAccessRoles replaces every role in the Lakehouse, so read the roles first and send the others back unchanged with the ETag you read.

​

Start a Run

1. Prepare the Run with POST /api/v1/fabric/runs and a new Run ID: {"id": "<new-uuid>", "pair_id": "<pair-id>"}. The response carries payload_base64 and report.token. The token comes back only from the call that prepared the Run; treat it as a secret and keep it out of logs. Retry with the same Run ID only to repeat that request.
2. Read workspace_id and pipeline_id from GET /api/v1/fabric/settings.
3. Start the validation pipeline in Fabric with an identity that has Contributor, Member, or Admin on that workspace:
   curl --fail-with-body --include \
     --header "Authorization: Bearer ${fabric_access_token}" \
     --header "Content-Type: application/json" \
     --data '{"executionData": {"parameters": {"mode": "run", "payload_base64": "<payload_base64>", "run_id": "<run-id>", "report_token": "<report.token>"}}}' \
     "https://api.fabric.microsoft.com/v1/workspaces/<workspace_id>/items/<pipeline_id>/jobs/instances?jobType=Pipeline"
   
4. Send the job ID, the last segment of the Location header in Fabric’s answer, with POST /api/v1/fabric/runs/<run-id>/submission and the body {"job_id": "<job-id>"}. The app then shows the Run as submitted and links it to Fabric Monitor.
5. Read GET /api/v1/fabric/runs/<run-id> until status is passed, failed, or error, and read each Test’s Result in the response.

​

Validate from a Fabric pipeline

1. A Web activity that prepares the Run. Its connection signs in as your workload’s app registration with service principal authentication, a secret, and the audience api://78d5d8af-9dd6-49dd-b06c-38c3a3c707af (connection type WebForPipeline), with the base URL https://api.generalvalidation.com. Use method POST, relative URL /api/v1/fabric/runs, and the body @concat('{"id":"', guid(), '","pair_id":"<pair-id>"}'). Turn on Secure output, because the answer holds the report token.
2. An Invoke pipeline activity that runs the General Validation pipeline in your Environment’s workspace and waits for it. Its connection uses your pipeline workspace’s identity (connection type FabricDataPipelines). Set the parameters mode to run, payload_base64 to @activity('<web activity>').output.payload_base64, run_id to @activity('<web activity>').output.id, and report_token to @activity('<web activity>').output.report.token. Turn on Secure input, and give the activity a timeout.