Dateien auf die Plattform hochladen

Viele Aufgaben erfordern, dass Sie eine Datei für die Legalesign-Plattform bereitstellen, z. B. eine Datei, die als Vorlage verwendet wird, oder ein Bild, das für eine Unterschrift verwendet wird.

Die Plattform verlangt, dass Sie diese Datei im richtigen Unterordner unseres Clearing-Systems ablegen. Dadurch wird Ihre Datei auf mögliche Sicherheitsprobleme geprüft und an den korrekten Ort für ihren Zweck weitergeleitet.

Vorlagen-Uploads

Wenn Sie ein Vorlagendokument hochladen möchten, verwenden Sie stattdessen die dedizierte Anleitung Eine Datei als Vorlage hochladen. Dieser Ablauf verwendet jetzt die von createTemplate zurückgegebene uploadUrl.

Was Sie Lernen Werden

Diese Anleitung führt Sie durch das Hochladen von Dateien zu Legalesign. Machen Sie sich keine Sorgen, wenn Sie neu bei APIs oder Cloud-Speicher sind – wir erklären jeden Schritt klar und verständlich.

Was ist eine Pre-Signed URL?

Eine Pre-Signed URL ist wie ein temporärer Zugangsausweis. Statt Ihnen dauerhaften Zugriff auf unseren Speicher zu geben, erhalten Sie eine spezielle URL, die:

• Nur für kurze Zeit (15 Minuten) gültig ist
• Nur das Hochladen einer bestimmten Datei erlaubt
• Ihre Dateien sicher hält

Man kann sie sich vorstellen wie ein Parkscheinticket für einen Valet-Service – sie gewährt zeitlich befristeten, eingeschränkten Zugang für einen bestimmten Zweck.

Was ist S3?

S3 (Simple Storage Service) ist Amazons Cloud-Dateispeicher. Dort speichern wir Ihre Dokumente, Logos und andere Dateien sicher. Sie müssen S3 nicht im Detail verstehen – wissen Sie nur, dass es ein sicherer Ort ist, um Dateien in der Cloud zu speichern.

Übersicht

Der Upload-Prozess folgt diesen Schritten:

1. Fordern Sie eine Pre-Signed Upload-URL an von der GraphQL-API (bitten Sie um Erlaubnis zum Hochladen)
2. Laden Sie Ihre Datei mit der bereitgestellten URL in S3 hoch (schicken Sie die Datei tatsächlich)
3. Die Plattform verarbeitet und prüft die Datei automatisch (wir stellen sicher, dass sie sicher ist)
4. Die Datei wird an ihren endgültigen Speicherort verschoben (wir legen sie an die richtige Stelle)

Warum dieser Zweischritt-Prozess?

Sie fragen sich vielleicht, warum wir keinen direkten Upload erlauben. Dieser Zweischritt-Prozess:

• Stellt sicher, dass Sie die Erlaubnis zum Hochladen haben
• Verhindert unautorisierte Datei-Uploads
• Ermöglicht uns, Dateien auf Viren zu prüfen
• Verfolgt, wer was hochgeladen hat

Schritt 1: Upload-URL anfordern

Verwenden Sie die upload-Abfrage, um eine Pre-Signed URL für Ihren Datei-Upload (in diesem Fall eine PDF) zu erhalten. Weitere Informationen zum Einstieg in GraphQL-Abfragen finden Sie in unserer Authentifizierungsanleitung. Details zu allen Argumenten finden Sie in der upload-Abfrage Referenz.

query {
  upload(
    id: "<BASE64_OBJECT_ID>",
    uploadType: TEMPLATE,
    extension: "pdf"
  ) {
    url
  }
}

Parameter erklärt

• id: Base64-kodierte Objekt-ID (z. B. Template-ID, Experience-ID)
• uploadType: Der Typ der hochzuladenden Datei (siehe unten)
• extension: Dateiendung (pdf, png, jpg)

Upload-Typen

• TEMPLATE - PDF-Dateien für Dokumentvorlagen
• LOGO - Bilder für das Branding der Unterschriftsseite
• EMAILLOGO - Bilder für das E-Mail-Branding
• ATTACHMENT - Zusätzliche Dateien zur Anfügung an Dokumente

Siehe UploadType Enum für die vollständige Liste.

Schritt 2: Upload zu S3

Die Abfrage liefert eine Pre-Signed URL zurück. Senden Sie Ihre Datei mit einer HTTP-PUT-Anfrage an diese URL:

const response = await fetch(url, {
  method: 'PUT',
  body: fileData,
  headers: {
    'Content-Type': 'application/pdf' // or appropriate MIME type
  }
});

Schritt 3: Automatische Verarbeitung

Nach dem Upload führt die Plattform folgende Schritte aus:

1. Scannt die Datei auf Viren und Sicherheitsbedrohungen
2. Prüft das Dateiformat und den Inhalt
3. Verarbeitet die Datei (z. B. Extrahiert Seitenmaße bei PDFs)
4. Verschiebt die Datei an den endgültigen Speicherort mit den entsprechenden Berechtigungen

Verfolgen Sie die Verarbeitung in Echtzeit

Wenn Sie nach Abschluss des S3-Uploads eine Echtzeit-Rückmeldung benötigen, verwenden Sie GraphQL-Subscriptions.

• Upload-Ereignisse werden über subscribeUserFeed geliefert
• Sie verwenden category: "upload"
• Typische Ereignisse sind uploadScanned, uploadTypeChecked, uploadCompleted und uploadFailed

Siehe Upload-Fortschritt mit Subscriptions verfolgen.

Komplettes Beispiel

JavaScript

import { generateClient } from 'aws-amplify/api';

const uploadFile = async (objectId, file) => {
  const client = generateClient();
  const extension = file.name.split('.').pop();
  
  // Step 1: Get upload URL
  const result = await client.graphql({
    query: `
      query {
        upload(
          id: "${objectId}",
          uploadType: TEMPLATE,
          extension: "${extension}"
        ) {
          url
        }
      }
    `
  });
  
  const uploadUrl = result.data.upload.url;
  
  // Step 2: Upload file
  const response = await fetch(uploadUrl, {
    method: 'PUT',
    body: file,
    headers: {
      'Content-Type': file.type
    }
  });
  
  if (!response.ok) {
    throw new Error('Upload failed');
  }
  
  return { success: true };
};

Python

import requests
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

def upload_file(graphql_endpoint, auth_token, object_id, file_path):
    extension = file_path.split('.')[-1]
    
    transport = RequestsHTTPTransport(
        url=graphql_endpoint,
        headers={'Authorization': auth_token}
    )
    client = Client(transport=transport, fetch_schema_from_transport=True)
    
    query = gql(f'''
        query {{
            upload(
                id: "{object_id}",
                uploadType: TEMPLATE,
                extension: "{extension}"
            ) {{
                url
            }}
        }}
    ''')
    
    result = client.execute(query)
    upload_url = result['upload']['url']
    
    with open(file_path, 'rb') as f:
        file_data = f.read()
    
    response = requests.put(
        upload_url,
        data=file_data,
        headers={'Content-Type': 'application/pdf'}
    )
    
    if response.status_code != 200:
        raise Exception('Upload failed')
    
    return {'success': True}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using GraphQL;
using GraphQL.Client.Http;
using GraphQL.Client.Serializer.Newtonsoft;

public class FileUploader
{
    public async Task<bool> UploadFile(string graphqlEndpoint, string authToken, 
                                       string objectId, string filePath)
    {
        var extension = Path.GetExtension(filePath).TrimStart('.');
        
        var graphQLClient = new GraphQLHttpClient(
            graphqlEndpoint, 
            new NewtonsoftJsonSerializer()
        );
        graphQLClient.HttpClient.DefaultRequestHeaders.Add("Authorization", authToken);
        
        var query = new GraphQLRequest
        {
            Query = $@"
                query {{
                    upload(
                        id: ""{objectId}"",
                        uploadType: TEMPLATE,
                        extension: ""{extension}""
                    ) {{
                        url
                    }}
                }}
            "
        };
        
        var response = await graphQLClient.SendQueryAsync<dynamic>(query);
        string uploadUrl = response.Data.upload.url;
        
        using var httpClient = new HttpClient();
        var fileBytes = await File.ReadAllBytesAsync(filePath);
        var content = new ByteArrayContent(fileBytes);
        content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/pdf");
        
        var uploadResponse = await httpClient.PutAsync(uploadUrl, content);
        
        if (!uploadResponse.IsSuccessStatusCode)
        {
            throw new Exception("Upload failed");
        }
        
        return true;
    }
}

Pfadformat

Dateien folgen dieser Namenskonvention:

<uploadType>/<userId>/<base64ObjectId>.<extension>

Beispiel:

template/usr123abc/dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx.pdf

Hinweis

Sie müssen diesen Pfad nicht selbst erstellen – die API übernimmt das automatisch, wenn Sie die korrekten Parameter angeben.

Unterstützte Dateitypen

Vorlagen

• Nur PDF-Dateien
• Maximalgröße: 50MB

Logos und E-Mail-Logos

• PNG, JPG, JPEG
• Maximalgröße: 5MB
• Empfohlene Abmessungen: 200x200px (Logos), 600x200px (E-Mail-Logos)

Anhänge

• PDF, DOC, DOCX, XLS, XLSX, PNG, JPG
• Maximalgröße: 25MB

Fehlerbehandlung

• Keine Berechtigung: Die Objekt-ID gehört nicht zu Ihrem Konto oder Ihrer Gruppe
• Ungültige Erweiterung: Dateityp wird für diesen Upload-Typ nicht unterstützt
• Datei zu groß: Überschreitet die maximale Größenbegrenzung
• Virus erkannt: Datei hat den Sicherheits-Scan nicht bestanden

Sicherheitshinweise

• Pre-Signed URLs verfallen nach 15 Minuten
• Dateien werden vor der Verarbeitung auf Viren gescannt
• Nur Benutzer mit entsprechenden Berechtigungen können Dateien hochladen
• Dateien sind während der Verarbeitung im Clearing-Bucket isoliert

Beste Vorgehensweisen

1. Prüfen Sie die Dateigröße immer vor dem Hochladen
2. Verwenden Sie das korrekte Dateiformat
3. Behandeln Sie Fehler sorgfältig
4. Verwenden Sie Pre-Signed URLs nicht mehrfach
5. Halten Sie Ihre Zugangsdaten sicher – teilen Sie niemals Authentifizierungs-Token oder betten Sie diese in klientenseitigen Code ein