Hur man skapar och uppdaterar en Spark-jobbdefinition med V2-format via Microsoft Fabric REST API

Spark-jobbdefinition (SJD) är en typ av Fabric-objekt som gör det möjligt för användare att definiera och köra Apache Spark-jobb i Fabric. Spark-jobbdefinitions-API:n v2 tillåter användare att skapa och uppdatera Spark-jobbdefinitionsobjekt med ett nytt format kallat SparkJobDefinitionV2. Den främsta fördelen med att använda v2-formatet är att användarna kan hantera den körbara huvudfilen och andra biblioteksfiler med ett enda API-anrop, i stället för att använda lagrings-API för att ladda upp filer separat behövs ingen mer lagringstoken för att hantera filer.

Förutsättningar

  • En token från Microsoft Entra krävs för att få åtkomst till Fabric REST API. MSAL-biblioteket (Microsofts autentiseringsbibliotek) rekommenderas för att hämta token. Mer information finns i Stöd för autentiseringsflöde i MSAL.

Fabric REST API definierar en enhetlig slutpunkt för CRUD-operationer av Fabric-objekt. Slutpunkten är https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items.

Översikt av Spark-jobbdefinition v2 formatöversikt

I nyttolasten för att hantera en Spark-jobbdefinitionspunkt definition används fältet för att specificera den detaljerade uppsättningen av Spark-jobbdefinitionsobjektet. Fältet definition innehåller två underfält: format och parts. Fältet format specificerar formatet för Spark-jobbdefinitionsobjektet, vilket ska gälla SparkJobDefinitionV2 för v2-formatet.

Fältet parts är en array som innehåller den detaljerade uppsättningen av Spark-jobbdefinitionsobjektet. Varje objekt i matrisen parts representerar en del av den detaljerade installationen. Varje del innehåller tre underfält: path, payloadoch payloadType. Fältet path anger sökvägen till delen, payload fältet anger innehållet i den del som är base64-kodad och payloadType fältet anger typen av nyttolast, som ska vara InlineBase64.

Viktigt!

Detta v2-format stöder endast Spark-jobbdefinitioner med filformat .py eller .scala. Det .jar filformatet stöds inte.

Skapa ett Spark-jobbdefinitionsobjekt med huvuddefinitionsfilen och andra biblioteksfiler

I följande exempel skapar vi en Spark-jobbdefinitionspunkt som:

  1. Namnet är SJDHelloWorld.
  2. Huvuddefinitionsfilen är main.py, vilket innebär att läsa en CSV-fil från dess standard sjöhus och spara som en Delta-tabell tillbaka till samma sjöhus.
  3. Annan lib-fil är libs.py, som har en verktygsfunktion för att returnera namnet på CSV-filen och Delta-tabellen.
  4. Standard-lakehouse är inställt på ett specifikt lakehouse-item-ID.

Följande är den detaljerade nyttolasten för att skapa Spark-jobbdefinitionsobjektet.

{
  "displayName": "SJDHelloWorld",
  "type": "SparkJobDefinition",
  "definition": {
    "format": "SparkJobDefinitionV2",
    "parts": [
      {
        "path": "SparkJobDefinitionV1.json",
        "payload": "<REDACTED>",
        "payloadType": "InlineBase64"
      },
      {
        "path": "Main/main.py",
        "payload": "<REDACTED>",
        "payloadType": "InlineBase64"
      },
      {
        "path": "Libs/lib1.py",
        "payload": "<REDACTED>",
        "payloadType": "InlineBase64"
      }
    ]
  }
}

Om du vill avkoda eller koda den detaljerade installationen kan du använda följande hjälpfunktioner i Python. Det finns också andra onlineverktyg som https://www.base64decode.org/ kan utföra samma jobb.

import base64

def json_to_base64(json_data):
    # Serialize the JSON data to a string
    json_string = json.dumps(json_data)
    
    # Encode the JSON string as bytes
    json_bytes = json_string.encode('utf-8')
    
    # Encode the bytes as Base64
    base64_encoded = base64.b64encode(json_bytes).decode('utf-8')
    
    return base64_encoded

def base64_to_json(base64_data):
    # Decode the Base64-encoded string to bytes
    base64_bytes = base64_data.encode('utf-8')
    
    # Decode the bytes to a JSON string
    json_string = base64.b64decode(base64_bytes).decode('utf-8')
    
    # Deserialize the JSON string to a Python dictionary
    json_data = json.loads(json_string)
    
    return json_data

Ett HTTP-kod 202-svar indikerar att Spark-jobbdefinitionsobjektet skapades framgångsrikt.

Få Spark-jobbdefinition med definitionsdelar under v2-formatet

Med det nya v2-formatet, när man hämtar ett Spark-jobbdefinitionsobjekt med definitionsdelar, inkluderas filinnehållet i huvuddefinitionsfilen och andra biblioteksfiler i svarspayloaden, base64 kodad under parts fältet. Här är ett exempel på att få en Spark-jobbdefinitionspunkt med definitionsdelar:

  1. Gör först en POST-begäran till slutpunkten https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{sjditemid}/getDefinitionParts?format=SparkJobDefinitionV2. Kontrollera att värdet för frågeparametern format är SparkJobDefinitionV2.
  2. Kontrollera sedan HTTP-statuskoden i svarshuvudena. En HTTP-kod 202 anger att begäran har godkänts. x-ms-operation-id Kopiera värdet från svarshuvudena.
  3. Slutligen gör du en GET-begäran till slutpunkten https://api.fabric.microsoft.com/v1/operations/{operationId} med det kopierade x-ms-operation-id värdet för att hämta åtgärdsresultatet. I responspayloaden definition innehåller fältet den detaljerade uppsättningen av Spark-jobbdefinitionsobjektet, inklusive huvuddefinitionsfilen och andra biblioteksfiler under parts fältet.

Uppdatera Spark-jobbdefinitionsobjektet med huvuddefinitionsfilen och andra biblioteksfiler under v2-format

För att uppdatera ett befintligt Spark-jobbdefinitionsobjekt med huvuddefinitionsfilen och andra bibliotekfiler under v2-formatet kan du använda en liknande payload-struktur som skapa-operationen. Här är ett exempel på att uppdatera Spark-jobbdefinitionsobjektet som skapades i föregående avsnitt:

{
  "displayName": "SJDHelloWorld",
  "type": "SparkJobDefinition",
  "definition": {
    "format": "SparkJobDefinitionV2",
    "parts": [
      {
        "path": "SparkJobDefinitionV1.json",
        "payload": "<REDACTED>",
        "payloadType": "InlineBase64"
      },
      {
        "path": "Main/main.py",
        "payload": "<REDACTED>",
        "payloadType": "InlineBase64"
      },
      {
        "path": "Libs/lib2.py",
        "payload": "<REDACTED>",
        "payloadType": "InlineBase64"
      }
    ]
  }
}

Med nyttolasten ovan görs följande ändringar i filerna:

  1. Filen main.py uppdateras med nytt innehåll.
  2. lib1.py tas bort från detta Spark-jobbdefinitionsobjekt och tas även bort från OneLake-lagringen.
  3. En ny lib2.py-fil läggs till i detta Spark-jobbdefinitionsobjekt och laddas upp till OneLake-lagringen.

För att uppdatera Spark-jobbdefinitionsobjektet, gör en POST-förfrågan till slutpunkten https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{sjditemid} med ovanstående nyttolast. Ett HTTP-kod 202-svar indikerar att Spark-jobbdefinitionsobjektet uppdaterades framgångsrikt.

Relaterat innehåll

  • Last updated on