Llwytho Ffeiliau i'r Llwyfan

Mae llawer o dasgau yn gofyn i chi ddarparu ffeil i’r llwyfan Legalesign ei defnyddio, megis ffeil i’w ddefnyddio fel templed neu ddelwedd i’w defnyddio ar gyfer llofnod.

Mae’r llwyfan yn gofyn i chi roi’r ffeil hon yn is-ffolder cywir ein system glanhau. Bydd hyn yn gwirio eich ffeil am faterion diogelwch posibl ac yn ei phasio ymlaen i’r lleoliad cywir ar gyfer ei bwrpas.

Llwytho Templedi

Os ydych chi am lwytho dogfen templed, defnyddiwch y canllaw penodol Upload a File as a Template. Mae’r llif hwnnw bellach yn defnyddio’r uploadUrl a ddychwelir gan createTemplate.

Beth Fyddwch Chi’n Dysgu

Bydd y canllaw hwn yn eich tywys drwy lwytho ffeiliau i Legalesign. Peidiwch â phoeni os ydych newydd i API neu storio cwmwl – byddwn yn egluro pob cam yn glir.

Beth yw URL Rhagosodedig?

Mae URL rhagosodedig fel pas mynediad drostrych. Yn hytrach nag rhoi mynediad parhaol i’r storfa, rhoddir URL arbennig i chi sy’n:

• Gweithio am gyfnod byr yn unig (15 munud)
• Caniatáu i chi lwytho un ffeil benodol yn unig
• Cadw’ch ffeiliau’n ddiogel

Meddyliwch amdano fel tocyn parcio valet – mae’n rhoi mynediad dros dro, cyfyngedig ar gyfer pwrpas penodol.

Beth yw S3?

S3 (Simple Storage Service) yw storfa ffeiliau cwmwl Amazon. Dyma lle rydym yn cadw’ch dogfennau, logos, a ffeiliau eraill yn ddiogel. Nid oes angen i chi ddeall S3’n fanwl – dim ond bod yn lle diogel i storio ffeiliau yn y cwmwl sydd ei angen arnoch.

Trosolwg

Mae’r broses lwytho yn dilyn y camau hyn:

1. Gofyn am URL lwytho rhagosodedig gan y GraphQL API (gofyn am ganiatâd i lwytho)
2. Llwytho’ch ffeil i S3 gan ddefnyddio’r URL a ddarparwyd (anfonwch y ffeil yn wirioneddol)
3. Mae’r llwyfan yn prosesu a dilysu’r ffeil yn awtomatig (rhydd ei wirio yn ddiogel)
4. Caiff y ffeil ei symud i’w lleoliad terfynol (rydym yn ei rhoi yn y lle cywir)

Pam y Broses Ddau Gam Hon?

Efallai rydych yn synnu pam na ddyrys ni chi lwytho’n uniongyrchol. Mae’r broses ddau gam hon yn:

• Sicrhau bod gennych ganiatâd i lwytho
• Atal llwytho ffeiliau anghymeradwy
• Caniatáu inni sganio ffeiliau am firysau
• Cadw cofnod o bwy wnaeth lwytho beth

Cam 1: Gofyn am URL Llwytho

Defnyddiwch y chwiliad upload i gael URL rhagosodedig ar gyfer lwytho’ch ffeil (yn yr achos hwn PDF). Gweler ein [canllaw awdurdodi] (./authenticate.md) am ragor o wybodaeth ar sut i ddechrau defnyddio chwiliadau GraphQL. Am fanylion llawn y dadleuon, gweler y cyfeirnod chwiliad upload.

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

Esboniad y Parametrau

• id: ID gwrthrych wedi’i godio Base64 (e.e., ID templed, ID profiad)
• uploadType: Y math o ffeil sy’n cael ei llwytho i fyny (gweler isod)
• extension: Estyniad ffeil (pdf, png, jpg)

Mathau o Lwythiadau

• TEMPLATE - Ffeiliau PDF ar gyfer templedi dogfen
• LOGO - Delweddau i frandio tudalen llofnodi
• EMAILLOGO - Delweddau i frandio e-bost
• ATTACHMENT - Ffeiliau ychwanegol i’w cysylltu â dogfennau

Gweler enum UploadType am y rhestr lawn.

Cam 2: Llwytho i S3

Mae’r chwiliad yn dychwelyd URL rhagosodedig. Anfonwch eich ffeil i’r URL hwn gan ddefnyddio cais HTTP PUT:

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

Cam 3: Prosesu Awtomatig

Unwaith wedi’u llwytho i fyny, mae’r llwyfan yn:

1. Sganio’r ffeil am firysau a bygythiadau diogelwch
2. Dilysu fformat a chynnwys y ffeil
3. Prosesu’r ffeil (er enghraifft, tynnu dimensiynau tudalen ar gyfer PDFau)
4. Ei symud i le storio terfynol gyda’r caniatadau priodol

Olrhain Prosesu mewn Amser Real

Os ydych angen adborth amser real ar ôl cwblhau’r lwytho i S3, defnyddiwch danysgrifiadau GraphQL.

• Caiff digwyddiadau llwytho eu cyflwyno ar subscribeUserFeed
• Maent yn defnyddio category: "upload"
• Mae digwyddiadau cyffredin yn cynnwys uploadScanned, uploadTypeChecked, uploadCompleted, a uploadFailed

Gweler Olrhain Cynnydd Llwytho gyda Thanysgrifiadau.

Enghraifft Gyntaf

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;
    }
}

Fformat Llwybr

Mae ffeiliau’n dilyn y cyfansoddiad enwau hyn:

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

Enghraifft:

template/usr123abc/dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx.pdf

nodyn

Nid oes angen i chi greu’r llwybr hwn eich hun – mae’r API yn ei drin yn awtomatig pan fyddwch yn darparu’r parametrau cywir.

Mathau o Ffeiliau a Ddylunir

Templedi

• Ffeiliau PDF yn unig
• Maint uchaf: 50MB

Logos a Logos E-bost

• PNG, JPG, JPEG
• Maint uchaf: 5MB
• Dimensiynau a argymhellir: 200x200px (logos), 600x200px (logos e-bost)

Atodiadau

• PDF, DOC, DOCX, XLS, XLSX, PNG, JPG
• Maint uchaf: 25MB

Delio ag Gwallau

• Dim caniatâd: Nid yw ID y gwrthrych yn perthyn i’ch cyfrif neu grŵp chi
• Estyniad annilys: Math o ffeil nad yw’n cael ei gefnogi ar gyfer y math hwn o lwytho
• Ffeil yn rhy fawr: Yn rhagori ar y terfyn maint uchaf
• Firys wedi’i ganfod: Methwyd y sgan diogelwch

Nodiadau Diogelwch

• Mae URL rhagosodedig yn dod i ben ar ôl 15 munud
• Caiff ffeiliau eu sganio am firysau cyn eu prosesu
• Dim ond defnyddwyr gyda’r caniatadau priodol sy’n gallu llwytho ffeiliau i fyny
• Mae ffeiliau’n cael eu cadw ar wahân yn ystod prosesu yn y bwced glanhau

Ymarferion Gorau

1. Gwiriwch yn gyson faint y ffeil cyn llwytho i fyny
2. Defnyddiwch y fformat ffeil cywir
3. Delio â gwallau yn ysgafn
4. Peidiwch â hailddefnyddio URLau rhagosodedig
5. Cadw eich manylion mewngofnodi yn ddiogel — paid â rhannu tocynnau awdurdodi na chyfuno hynny â chôd cleient y porwr