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 defnyddio fel templed neu ddelwedd i’w defnyddio ar gyfer llofnod.

Llwytho Templedi

Os ydych am lwytho dogfen dempled, defnyddiwch y canllaw arbennig Llwytho Ffeil Fel Templed yn lle hynny. Mae’r llif hwnnw bellach yn defnyddio’r uploadUrl a ddychwelydwyd gan createTemplate.

Beth Bydda Chi'n Dysgu

Bydd y canllaw hwn yn eich tywys drwy lwytho ffeiliau i Legalesign. Peidiwch â phoeni os ydych newydd i APIau neu storfa cwmwl – esboniwn bob cam yn glir.

Beth yw URL Rhagosodedig

Mae URL rhagosodedig yn debyg i bas mynediad dros dro. Yn lle rhoi mynediad parhaol i’n storfa i chi, rydym yn rhoi URL arbennig sy’n:

• Gweithio dim ond am gyfnod byr (15 munud)
• Yn caniatáu i chi lwytho un ffeil benodol yn unig
• Yn cadw eich ffeiliau yn ddiogel

Meddyliwch amdano fel tocyn parcio valet - mae’n rhoi mynediad dros dro, cyfyngedig at bwrpas penodol.

Beth yw S3?

Mae S3 (Gwasanaeth Storio Syml) yn storfa ffeil ar y cwmwl gan Amazon. Dyma lle rydym yn storio eich dogfennau, logos, a ffeiliau eraill yn ddiogel. Nid oes angen i chi ddeall S3 yn fanwl – dim ond gwybod ei fod yn fan diogel i storio ffeiliau yn y cwmwl.

Trosolwg

Mae’r broses lwytho yn dilyn y camau hyn:

1. Gofyn am URL llofnod rhagosodedig gan y GraphQL API (gwneud cais am ganiatâd i lwytho)
2. Llwytho eich ffeil i S3 gan ddefnyddio’r URL a ddarparwyd (anfon y ffeil mewn gwirionedd)
3. Mae’r llwyfan yn prosesu yn awtomatig ac yn dilysu’r ffeil (rydym yn gwirio ei bod yn ddiogel)
4. Symudir y ffeil i’w man cyrchfan terfynol (rydym yn ei roi yn y lle cywir)

Pam y Broses Dau-Gam Hon?

Efallai’ch bod yn pendroni pam nad ydym yn caniatáu i chi lwytho yn uniongyrchol. Mae’r broses dau-gam hon yn:

• Sicrhau eich bod wedi cael caniatâd i lwytho
• Atal lwytho ffeiliau di-gymeradwyaeth
• Caniatáu i ni sganio ffeiliau am firysau
• Cadw olrhain o bwy wnaeth lwytho beth

Cam 1: Gofyn am URL Llwytho

Defnyddiwch y cwestiwn upload i gael URL llofnod rhagosodedig ar gyfer eich llwytho ffeil (yn yr achos hwn PDF). Edrychwch ar ein canllaw dilysu am fwy o wybodaeth ar sut i ddechrau rhedeg ymholiadau GraphQL. Am fanylion llawn am y dadleuon, gweld y cyfeirnod cwestiwn upload.

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

Esboniwyd Paramedrau

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

Mathau o Lwytho

• TEMPLATE - Ffeiliau PDF ar gyfer templedi dogfennau
• LOGO - Delweddau ar gyfer brandio tudalen llofnodi
• EMAILLOGO - Delweddau ar gyfer brandio e-bost
• ATTACHMENT - Ffeiliau ychwanegol i’w hatodi at ddogfennau

Gweler UploadType enum am y rhestr lawn.

Cam 2: Llwytho i S3

Mae’r cwestiwn yn dychwelyd URL llofnod 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 y bydd y ffeil wedi ei lwytho, mae’r llwyfan yn:

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

Olrhain Prosesu mewn Amser Real

Os oes angen adborth amser real arnoch ar ôl cwblhau’r llwytho i S3, defnyddiwch danysgrifiadau GraphQL.

• Caiff digwyddiadau llwytho eu danfon ar subscribeUserFeed
• Maent yn defnyddio category: "upload"
• Digwyddiadau cyffredin yw 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 yn dilyn y traddodiad enwi hwn:

<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 ddelio’n awtomatig pan fyddwch yn darparu’r paramedrau cywir.

Mathau o Ffeiliau sy'n cael eu Cefnogi

Templedi

• Ffeiliau PDF yn unig
• Maint uchaf: 50MB

Logos a Logos E-bost

• PNG, JPG, JPEG
• Maint uchaf: 5MB
• Dimensiynau argymelledig: 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’r ID gwrthrych yn perthyn i’ch cyfrif neu grŵp
• Estyniad annilys: Math y ffeil ddim yn cael ei gefnogi ar gyfer y math hwn o lwytho
• Ffeil yn rhy fawr: Yn troseddio ar y terfyn maint uchaf
• Firws wedi’i ganfod: Wedi methu sgan diogelwch

Nodiadau Diogelwch

• Bydd URLau llofnod rhagosodedig yn dod i ben ar ôl 15 munud
• Mae ffeiliau yn cael eu sganio am firysau cyn prosesu
• Dim ond defnyddwyr gyda’r caniatadau priodol all lwytho ffeiliau
• Mae ffeiliau’n cael eu cadw ar wahân yn ystod prosesu yn y fag codi clirio

Ymarferion Gorau

1. Gwirio maint y ffeil bob amser cyn llwytho i fyny
2. Defnyddio’r fformat ffeil cywir
3. Delio â gwallau yn derbyniol
4. Peidiwch â defnyddio URLau llofnod rhagosodedig unwaith eto
5. Cadw eich cymwysterau’n ddiogel — peidiwch byth â rhannu tocynnau dilysu nac yn eu mewnosod yn y cod ar ochr y cleient