एसेट अपलोड के लिए हस्ताक्षरित URL पाएँ

परिचय

वर्कस्पेस के मीडिया ऑब्जेक्ट का हस्ताक्षरित अपलोड URL पाएँ। उस URL पर फ़ाइल बाइट अपलोड करें, फिर एसेट पंजीकरण के लिए upload/complete कॉल करें। यह एंडपॉइंट आपके लिए लोकल फ़ाइल नहीं पढ़ता।

सफल HTTP रिस्पॉन्स का अर्थ अनुरोध पूरा होने के बजाय स्वीकार होना हो सकता है। बैकग्राउंड काम में लौटाई ID सहेजें और समाप्ति तक वही ऑपरेशन जाँचें। निर्धारित या स्वीकृत पोस्ट प्लेटफ़ॉर्म की पुष्टि पर ही प्रकाशित है; क्लाइंट टाइमआउट परिणाम सिद्ध नहीं करता।

प्रमाणीकरण और अनुमतियाँ

स्वीकार्य क्रेडेंशियल श्रेणियाँ

user_session, delegated_oauth, personal_access_token

प्रत्यायोजित क्षमता

agent:operate

न्यूनतम वर्कस्पेस भूमिका

editor

एक्सेस का दायरा

वे संसाधन जिनके एक्सेस के लिए यह यूज़र अधिकृत है

सभी वर्कस्पेस के लिए सहमति आवश्यक

नहीं

स्थिति बदलता है

हाँ

ऑपरेशन पूरा होने पर

synchronous_http_response

टोकन केवल मालिक के अधिकार इस्तेमाल कर सकता है। हर अनुरोध वर्कस्पेस सदस्यता, संसाधन स्वामित्व, चुने वर्कस्पेस और दी क्षमताएँ जाँचता है। Core और full प्रोफ़ाइल दिखने वाले टूल बदलते हैं; एक्सेस नहीं देते।

अनुरोध के फ़ील्ड

Required का अर्थ पैरेंट ऑब्जेक्ट और चुनी शाखा के भीतर अनिवार्य है। अनिवार्य चाइल्ड से वैकल्पिक पैरेंट अनिवार्य नहीं होता। नीचे के नियम और फ़ील्ड नाम कॉन्ट्रैक्ट से लिए गए हैं।

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "asset_type": {
      "type": "string",
      "enum": [
        "image",
        "video"
      ]
    },
    "filename": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "content_type": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "byte_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 524288000,
      "description": "Exact length in bytes of the body you will PUT (max 500 MiB). It is signed into the upload URL as Content-Length, counted against the workspace storage limit, and checked again when you complete the upload: an object longer than declared is rejected and removed."
    },
    "content_sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "title": {
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "workspace_id",
    "asset_type",
    "filename",
    "content_type",
    "byte_size",
    "content_sha256"
  ],
  "additionalProperties": false
}

रिस्पॉन्स और पूर्णता

सफल HTTP स्टेटस: 200. When the operation is complete: synchronous_http_response.

सफल HTTP रिस्पॉन्स का अर्थ अनुरोध पूरा होने के बजाय स्वीकार होना हो सकता है। बैकग्राउंड काम में लौटाई ID सहेजें और समाप्ति तक वही ऑपरेशन जाँचें। निर्धारित या स्वीकृत पोस्ट प्लेटफ़ॉर्म की पुष्टि पर ही प्रकाशित है; क्लाइंट टाइमआउट परिणाम सिद्ध नहीं करता।

Required का अर्थ पैरेंट ऑब्जेक्ट और चुनी शाखा के भीतर अनिवार्य है। अनिवार्य चाइल्ड से वैकल्पिक पैरेंट अनिवार्य नहीं होता। नीचे के नियम और फ़ील्ड नाम कॉन्ट्रैक्ट से लिए गए हैं।

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "object_key": {
      "type": "string",
      "minLength": 1
    },
    "public_url": {
      "type": "string",
      "format": "uri"
    },
    "signed_url": {
      "type": "string",
      "format": "uri"
    },
    "upload_headers": {
      "type": "object",
      "properties": {
        "Content-Type": {
          "type": "string",
          "minLength": 1
        },
        "x-amz-checksum-sha256": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "Content-Type",
        "x-amz-checksum-sha256"
      ]
    },
    "expires_seconds": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "object_key",
    "public_url",
    "signed_url",
    "upload_headers",
    "expires_seconds"
  ]
}

त्रुटियाँ और सुरक्षित पुनः प्रयास

HTTP स्टेटस और रिस्पॉन्स बॉडी जाँचें। 400 वैलिडेशन त्रुटि में ZodError हो सकता है; हैंडलर त्रुटियाँ error, message और code फ़ील्ड इस्तेमाल करती हैं। जाँच के लिए request_id या x-request-id रखें, क्रेडेंशियल के बिना। फिर प्रयास से पहले 401/403 एक्सेस त्रुटियाँ ठीक करें और 429 के लिए Retry-After का पालन करें। राइट अनिश्चित हो या 5xx लौटाए, तो पहले मौजूदा परिणाम पढ़ें। idempotency key केवल समर्थित स्थान पर दोबारा इस्तेमाल करें; पुनः प्रयास का व्यवहार ऑपरेशन के अनुसार बदलता है और ठीक एक बार डिलीवरी की गारंटी नहीं देता।

उदाहरण

उदाहरणों में स्कीमा से जाँचे काल्पनिक मान हैं। IDs को अधिकृत IDs, मीडिया को तैयार एसेट और तारीखों को पुष्ट प्रकाशन समय से बदलें। राइट सबमिट करने से पहले खाते की पात्रता जाँचें। यह पेज API अनुरोध नहीं भेजता।

सर्वर पर SOSOAPI_ACCESS_TOKEN को इस ऑपरेशन के स्वीकार्य क्रेडेंशियल से सेट करें और ब्राउज़र कोड से बाहर रखें। एजेंट के लिए sosoapi auth login से ब्राउज़र साइन-इन करें और CLI को क्रेडेंशियल रिफ़्रेश करने दें।

request.json

{
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "asset_type": "image",
  "filename": "example.png",
  "content_type": "image/png",
  "byte_size": 1,
  "content_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

cURL

curl --request POST \
  "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/assets-api/upload/sign" \
  -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

JavaScript

// Server-side JavaScript. Do not print tokens or credential-bearing responses.
const token = process.env.SOSOAPI_ACCESS_TOKEN;
if (!token) throw new Error("Set an accepted credential for this operation");
const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/assets-api/upload/sign", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
  body: JSON.stringify({
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "asset_type": "image",
  "filename": "example.png",
  "content_type": "image/png",
  "byte_size": 1,
  "content_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
})
});
const result = await response.json();
// Check response.ok, the operation-specific body and completion state before continuing.

CLI

npx sosoapi api post /assets-api/upload/sign < request.json

कृत्रिम रिस्पॉन्स का उदाहरण

{
  "object_key": "example",
  "public_url": "https://example.com/media.png",
  "signed_url": "https://example.com/media.png",
  "upload_headers": {
    "Content-Type": "example",
    "x-amz-checksum-sha256": "example"
  },
  "expires_seconds": 1
}

संबंधित टूल और गाइड

MCP: sosoapi_upload_asset