Transformasjonsfunksjoner

Kartlegging henter ut verdier fra en forespørsel. En transformasjonsfunksjon går et skritt videre: Det er din egen JavaScript-kode som kjøres på hver forespørsel før den når Shopify Flow, slik at du kan omforme datapakken, slå opp noe, avgjøre om forespørselen i det hele tatt er verdt å kjøre en arbeidsflyt for, eller svare avsenderen selv.

Den finnes på fanen Funksjon i en webhook. Et tomt redigeringsfelt betyr at funksjonen er deaktivert.

En funksjons form

export default async function transform(payload, ctx) {
  // payload - the parsed request body (JSON, form or XML)
  // return an object -> it becomes the payload for mapping and Flow
  // return null      -> nothing is sent to Flow, and nothing counts
  return { ...payload, source: "warehouse" }
}

Hva ctx gir deg

ctx.request	method, contentType, forespørselens headers (hemmelige opplysninger er skjult) og query
ctx.webhook	Webhookens id og name
ctx.shop	Ditt myshopify-domene
ctx.log(...)	Skriver en linje som du kan lese i testpanelet og i historikken
await ctx.fetch(url, init)	Kaller et offentlig API
await ctx.shopify(query, variables)	Henter data fra butikken med Admin GraphQL
ctx.storage	Beholder små verdier mellom kjøringene (se nedenfor)
ctx.respond(body, options)	Svarer innringeren umiddelbart

Omstrukturering av nyttelasten

Den vanligste bruken: å omforme en avsenders struktur til de få verdiene arbeidsflyten din trenger.

export default async function transform(payload) {
  const order = payload.data.attributes
  return {
    orderNumber: String(order.number),
    email: order.customer.email.toLowerCase(),
    total: Number(order.total_cents) / 100,
  }
}

Fjerne forespørsler du ikke trenger

Returner null, så stopper forespørselen der: ingen kjøring av Shopify Flow, ingen historikkoppføring og ingenting som trekkes fra abonnementet ditt. Den som sender forespørselen får 200 med { "skipped": true }, så den prøver ikke på nytt.

export default async function transform(payload, ctx) {
  if (payload.status !== "paid" || payload.total < 100) {
    ctx.log("skipping", payload.id, payload.status, payload.total)
    return null
  }
  return payload
}

Å huske ting mellom løpeturene

ctx.storage er et lite nøkkel-verdi-lager som tilhører nettbutikken din. Det er verktøyet som hjelper deg med å finne ut om du har sett dette før: lagre en ID når en hendelse kommer inn, og hopp over neste forespørsel med samme ID, selv om den kommer flere dager senere.

Ring	Gjør
await ctx.storage.get(key)	Den lagrede verdien, eller null
await ctx.storage.set(key, value)	Lagrer en hvilken som helst JSON-verdi og overskriver
await ctx.storage.delete(key)	Fjerner den; true hvis den fantes
await ctx.storage.list({ prefix, limit, cursor })	Viktige betegnelser og størrelser, side for side

export default async function transform(payload, ctx) {
  const key = `seen:${payload.id}`
  if (await ctx.storage.get(key)) return null
  await ctx.storage.set(key, { at: Date.now() })
  return payload
}

Berikelse med butikkdata

ctx.shopify kjører skrivebeskyttede Admin GraphQL-spørringer for butikken din, slik at en arbeidsflyt kan starte med data som avsenderen aldri har hatt tilgang til. Den ser bare det du tillater: Gi tilgang til de områdene du trenger under Tilgang til butikkdata på fanen «Funksjon». Ingenting er tillatt som standard, og mutasjoner avvises.

export default async function transform(payload, ctx) {
  const data = await ctx.shopify(
    `query($q: String!) {
      productVariants(first: 1, query: $q) { nodes { id title price } }
    }`,
    { q: `sku:${payload.sku}` },
  )
  const variant = data.productVariants.nodes[0]
  if (!variant) return null
  return { sku: payload.sku, variantId: variant.id, price: variant.price }
}

Å svare på anropet selv

ctx.respond() sender et svar tilbake umiddelbart, noe som gjør webhooken til et lite API-endepunkt: valider noe, beregn et svar og svar i én forespørsel. Shopify Flow fortsetter å kjøre uansett hva du returnerer.

export default async function transform(payload, ctx) {
  const ok = typeof payload.email === "string" && payload.email.includes("@")
  ctx.respond({ accepted: ok }, { status: ok ? 200 : 422 })
  return ok ? payload : null
}

Testing

Testpanelet på fanen «Funksjon» kjører koden i redigeringsverktøyet - inkludert ubehandlede endringer - mot en eksempeldata. Det viser returverdien, svaret funksjonen din ville sendt, Shopify Flow-feltene den genererer, logglinjene dine og varigheten. Ingenting utløser Shopify Flow, ingenting skrives til historikken, og ingenting teller med i abonnementet ditt. Lagringsanropene er imidlertid ekte: en testkjøring leser og skriver til samme butikk som live-forespørsler.

Når en funksjon mislykkes

Hvis koden din kaster en unntak, går ut på tid eller returnerer noe ubrukelig, blir forespørselen avvist med feilkoden 422, og feilen registreres i History sammen med feilmeldingen og logglinjene dine, slik at du kan se hva som skjedde. Rett opp koden og kjør oppføringen på nytt: da kjører den nye versjonen.

Grenser

• 5 sekunder og 64 MB per kjøring, samt 50 000 tegn med kode.
• Ingen npm-pakker. ctx.fetch er den eneste løsningen, og interne eller private adresser avvises.
• ctx.shopify tillater 10 forespørsler per kjøring, kun søk, begrenset til de omfangene du har gitt tillatelse til.
• Hver kjøring som når Shopify Flow, regnes som en vanlig utløsning og teller med i abonnementet ditt. En forbigått forespørsel teller ikke med.