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 werden soll, oder ein Bild, das für eine Unterschrift verwendet wird.

Vorlage hochladen

Wenn Sie ein Vorlagendokument hochladen möchten, verwenden Sie stattdessen die spezielle Anleitung Datei als Vorlage hochladen. Dieser Ablauf nutzt nun die von createTemplate zurückgegebene uploadUrl.

Was Sie Lernen Werden

Diese Anleitung führt Sie durch das Hochladen von Dateien zu Legalesign. Keine Sorge, wenn Sie neu in 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 Zugangspass. Anstatt Ihnen dauerhaften Zugriff auf unseren Speicher zu geben, erhalten Sie eine spezielle URL, die:

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

Man kann sie sich wie einen Parkschein für den Parkservice vorstellen – sie gibt temporären, eingeschränkten Zugriff 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 einfach, dass es ein sicherer Ort ist, um Dateien in der Cloud zu speichern.

Überblick

Der Hochladeprozess folgt diesen Schritten:

1. Anfrage einer pre-signed Upload-URL über die GraphQL-API (Erlaubnis zum Hochladen anfragen)
2. Datei-Upload zu S3 mittels der bereitgestellten URL (die Datei tatsächlich hochladen)
3. Die Plattform verarbeitet und validiert die Datei automatisch (wir prüfen, dass sie sicher ist)
4. Die Datei wird an ihren endgültigen Speicherort verschoben (wir legen sie an den richtigen Ort)

Warum dieser Zwei-Schritte-Prozess?

Vielleicht fragen Sie sich, warum wir Sie nicht direkt hochladen lassen. Dieser Zwei-Schritte-Prozess:

• Stellt sicher, dass Sie Erlaubnis zum Hochladen haben
• Verhindert unautorisierte Datei-Uploads
• Ermöglicht die Virensuche in den Dateien
• Verfolgt, wer was hochgeladen hat

Schritt 1: Upload-URL anfragen

Verwenden Sie die upload Query, um eine Pre-Signed URL für Ihren Datei-Upload zu erhalten (hier ein PDF). Weitere Informationen zum Einstieg in GraphQL-Abfragen finden Sie in unserem Authentifizierungsleitfaden. Für vollständige Argumentdetails siehe die upload Query-Referenz.

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

Parametererklärung

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

Upload-Typen

• TEMPLATE - PDF-Dateien für Dokumentvorlagen
• LOGO - Bilder für die Gestaltung der Unterschriftsseite
• EMAILLOGO - Bilder für das E-Mail-Branding
• ATTACHMENT - Zusätzliche Dateien, die an Dokumente angehängt werden

Eine vollständige Liste finden Sie im UploadType Enum.

Schritt 2: Upload zu S3

Die Query 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. Validiert das Dateiformat und den Inhalt
3. Verarbeitet die Datei (z. B. Extrahieren von Seitenmaßen bei PDFs)
4. Verschiebt sie an den endgültigen Speicherort mit entsprechenden Berechtigungen

Verarbeitung in Echtzeit verfolgen

Wenn Sie nach dem Abschluss des S3-Uploads Echtzeit-Feedback benötigen, verwenden Sie GraphQL-Subscriptions.

• Upload-Ereignisse werden über subscribeUserFeed geliefert
• Sie benutzen 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 Benennungs-Konvention:

<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 richtigen Parameter angeben.

Unterstützte Dateitypen

Vorlagen

• Nur PDF-Dateien
• Maximale Größe: 50MB

Logos und E-Mail-Logos

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

Anhänge

• PDF, DOC, DOCX, XLS, XLSX, PNG, JPG
• Maximale Größ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 das Größenlimit
• Virus entdeckt: Datei hat den Sicherheitscheck nicht bestanden

Sicherheitshinweise

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

Best Practices

1. Prüfen Sie immer die Dateigröße vor dem Hochladen
2. Verwenden Sie das korrekte Dateiformat
3. Gehen Sie mit Fehlern sorgfältig um
4. Verwenden Sie keine Pre-Signed URLs mehrfach
5. Halten Sie Ihre Zugangsdaten sicher — teilen Sie niemals Auth-Tokens oder binden Sie diese in clientseitigem Code ein