Słownik

Jak initializeUpload na LinkedInie zamienia plik w URN obrazu

Taras Shynkarenko
Taras Shynkarenko
•Zaktualizowano: •8 min czytania
Jak initializeUpload na LinkedInie zamienia plik w URN obrazuJak initializeUpload na LinkedInie zamienia plik w URN obrazu

TL;DR, szybka odpowiedź

8 min czytania

Publikacja obrazu na LinkedInie wymaga trzech wywołań. POST /rest/images?action=initializeUpload rejestruje przesyłanie i zwraca uploadUrl, znacznik czasu uploadUrlExpiresAt oraz URN obrazu w postaci urn:li:image:{id}. Następnie wysyłasz plik pod ten adres, co strona Assets opisuje jako PUT z tokenem OAuth, i podajesz URN jako content.media.id w POST /rest/posts. Każdy etap ma własną tabelę błędów, a LinkedIn nie opisuje innej drogi ponowienia nieudanego przesłania niż rozpoczęcie od nowa.

Co robi wywołanie initializeUpload na LinkedInie?

Wywołanie initializeUpload na LinkedInie rejestruje przesyłanie obrazu, zanim zostanie wysłany choćby jeden bajt, i zwraca adres, pod który należy wysłać plik, oraz URN, do którego odwoła się post. Opis LinkedIna ma trzy zdania: "Use the initializeUpload action to register the upload. When you initialize, you declare the upcoming upload. Use the upload URL to upload the image."

To wywołanie jest akcją w Images API, przekazywaną jako parametr zapytania:

POST https://api.linkedin.com/rest/images?action=initializeUpload
Authorization: Bearer {INSERT_TOKEN}
Linkedin-Version: 202608
X-Restli-Protocol-Version: 2.0.0
 
{
  "initializeUploadRequest": {
    "owner": "urn:li:organization:5583111"
  }
}

Jedyne wymagane pole to initializeUploadRequest.owner, opisane jako "URN of the entity that owns this asset. Can be a person(urn:li:person:123), or organization(urn:li:organization:123) URN." Warto porównać to ze schematem samego obrazu, gdzie pole owner najwyższego poziomu przyjmuje też URN sponsoredAccount. Żądanie inicjalizacji wymienia tylko osobę i organizację.

Opcjonalne drugie pole od razu rejestruje zasób w bibliotece multimediów konta reklamowego:

{
  "initializeUploadRequest": {
    "owner": "urn:li:organization:2414183",
    "mediaLibraryMetadata": {
      "associatedAccount": "urn:li:sponsoredAccount:123456789",
      "assetName": "My media library asset"
    }
  }
}

mediaLibraryMetadata.mediaLibraryStatus "defaults to ACTIVE on creation", więc zasób w bibliotece jest aktywny, gdy tylko skończy się jego przetwarzanie.

Jedną uwagę dokumentacja wyróżnia w ramce, bo przełamuje ona nawyk przeniesiony ze starszego Assets API: "SYNCHRONOUS_UPLOAD is not supported in Images API." Nie ma skrótu w postaci jednego wywołania. Trzy kroki to wszystko, co jest dostępne.

Co zwraca initializeUpload?

Odpowiedź 200 z trzema wartościami opakowanymi w value:

{
   "value": {
       "uploadUrlExpiresAt": 1650567510704,
       "uploadUrl": "https://www.linkedin.com/dms-uploads/C4E10AQFoyyAjHPMQuQ/uploaded-image/0?ca=vector_ads&cn=uploads&sync=0&v=beta&ut=08zHQjMjAOLqc1",
       "image": "urn:li:image:C4E10AQFoyyAjHPMQuQ"
   }
}

Wartość image to URN i właśnie ją trzeba zapisać. Wszystkie dalsze kroki odwołują się do obrazu tym ciągiem: treść posta, GET sprawdzający status przetwarzania, lista biblioteki multimediów. Zwróć uwagę, że identyfikator w URN jest taki sam jak identyfikator w ścieżce adresu przesyłania, co ułatwia powiązanie ich w logach.

uploadUrlExpiresAt to liczba milisekund od początku epoki. LinkedIn nie podaje długości tego okna, więc należy odczytywać znacznik czasu, a nie zakładać konkretny czas trwania. Kolejka, która inicjalizuje partię przesłań na kilka godzin przed wysłaniem plików, polega na wartości, której nikt nie udokumentował.

URN obrazu ma też format, który warto walidować po swojej stronie, bo Images API odrzuca nieprawidłowe wartości osobnym błędem: urn:li:image:, po nim identyfikator i nic więcej. Images API przyjmuje "Images with less than 36,152,320 pixels" w "JPG, GIF, and PNG formats", a przy tym "GIF format supports up to 250 frames."

Ekran telefonu z trwającym przesyłaniem pliku, czyli etap, w którym bajty obrazu trafiają pod adres z initializeUpload.

Jak przesłać bajty obrazu?

Na uploadUrl, z plikiem jako treścią żądania i tym samym tokenem bearer. Strona Assets, do której na tym etapie odsyła Images API, jasno określa metodę: "Use the uploadUrl from the previous step to upload the image. Use a PUT method to upload the image. The upload call requires a valid OAuth token in the 'Authorization' header. This is different than the upload video call which doesn't accept an OAuth token."

curl -i --upload-file ~/Desktop/Myimage.jpg \
  -H 'Authorization: Bearer Redacted' \
  "https://www.linkedin.com/dms-uploads/C5622AQHdBDflPp0pEg/feedshare-uploadedImage/0?ca=vector_feedshare&cn=uploads&sync=1&v=beta&ut=1lrKqjt4fYuqw1"

Udane przesłanie kończy się odpowiedzią HTTP/2 201 z content-length: 0. Bez treści, bez JSON-a, bez czegokolwiek do parsowania. Dowiadujesz się tylko kodu statusu.

LinkedIn przeczy sam sobie w kwestii metody i warto o tym wiedzieć, zanim zaczniesz debugować błąd 405. Konsumencki przewodnik Share on LinkedIn, opisujący starszy proces /v2/assets, każe "send a POST request to the uploadUrl with your image or video included as a binary file", po czym pokazuje to przez curl -i --upload-file, czyli PUT. Strona Assets w tekście mówi o PUT i pokazuje to samo polecenie. Polecenie jest najbardziej wiarygodną częścią obu stron.

Po przesłaniu GET https://api.linkedin.com/rest/images/urn:li:image:C4E10AQFn10iWtKexVA zwraca zasób z polem status. Udokumentowane wartości to WAITING_UPLOAD ("Waiting for client to upload source file or uploading process to be completed"), PROCESSING, AVAILABLE ("All of the recipe's required artifacts are ready. The asset is available to be served") oraz PROCESSING_FAILED, który schemat przypisuje do "client error such as file size too large, unsupported file format, internal error."

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Przy tym GET czyha pułapka uprawnień: Images API wymaga rw_ads, w_member_social, w_organization_social lub w_power_creators, a LinkedIn zaznacza, że "w_member_social permission are write-only and tokens with only w_member_social permissions would be unable to perform a GET call for rest/images." Integracja z zakresem członka może przesyłać, ale nie może odpytywać o status.

Jak odwołać się do URN obrazu w poście?

Jako content.media.id w Posts API, obok tekstu alternatywnego:

POST https://api.linkedin.com/rest/posts
 
{
  "author": "urn:li:organization:5515715",
  "commentary": "test strings!",
  "visibility": "PUBLIC",
  "distribution": {
    "feedDistribution": "MAIN_FEED",
    "targetEntities": [],
    "thirdPartyDistributionChannels": []
  },
  "content": {
    "media": {
      "altText": "testing for alt tags",
      "id": "urn:li:image:C5610AQFj6TdYowm17w"
    }
  },
  "lifecycleState": "PUBLISHED",
  "isReshareDisabledByAuthor": false
}

"A successful response returns a 201 Created HTTP status code and the ID in the x-restli-id response header." URN posta wraca w nagłówku, a nie w treści odpowiedzi, i wygląda jak urn:li:share:6844785523593134080 albo urn:li:ugcPost:68447855235931240. Integracje, które czytają tylko treść odpowiedzi, całkowicie tracą identyfikator posta.

Pole altText w tym obiekcie multimediów ma własny udokumentowany limit, omówiony w tekście o tym, gdzie LinkedIn zapisuje limit tekstu alternatywnego. W poście z wieloma obrazami te same URN trafiają do tablicy images, z minimum 2 i maksimum 20 elementów.

Osoba czyta komunikat o błędzie na ekranie laptopa, co oddaje debugowanie po nieudanym przesłaniu lub publikacji.

Jakie błędy pojawiają się na każdym etapie?

Trzy etapy, trzy osobne tabele błędów, które się nie pokrywają.

EtapStatusKodZnaczenie
initializeUpload400INVALID_URN_TYPE"{field} value {value} must be a {urnType} URN"
initializeUpload400INVALID_URN_ID"This URN ID is invalid"
initializeUpload403nie opublikowano"Accessing this image resource is forbidden. Please check your permissions for this resource"
initializeUpload400VERSION_MISSINGW żądaniu pominięto nagłówek wersji
Przesyłanie PUT401UNAUTHORIZED"The OAuth token is missing, invalid, or expired"
Przesyłanie PUT413REQUEST_ENTITY_TOO_LARGE"The uploaded file exceeds the allowed size limit"
Przesyłanie PUT415UNSUPPORTED_MEDIA_TYPE"The uploaded file format is not supported"
Przesyłanie PUT422UNPROCESSABLE_ENTITY"The server understands the request but can't process it"
POST /rest/posts400INVALID_URN_TYPE"Verify the URN type used for fields such as author or content.media.id"
POST /rest/posts400MISSING_FIELDBrak author, visibility, distribution lub lifecycleState
POST /rest/posts403ACCESS_DENIEDZakres przyznany, ale członek nie ma roli na stronie firmowej
POST /rest/posts429TOO_MANY_REQUESTS"The API rate limit has been exceeded"

Błąd 403 przy inicjalizacji wymaga uważnej lektury, bo LinkedIn publikuje go jako surową treść, a nie kod, a jego przyczyną jest zwykle rola na stronie, a nie zakres. Udokumentowane kontrole uprawnień opierają się na rolach: "For images with company URN owners, the caller must have ADMIN or DSC permissions for the company page" oraz "For images with member URN owners, the caller must match the image owner."

Brak nagłówka wersji powoduje niepowodzenie inicjalizacji, zanim cokolwiek z tego zostanie ocenione, z błędem 400 VERSION_MISSING i komunikatem "A version must be present. Please specify a version by adding the Linkedin-Version header." Zasady dotyczące tego nagłówka, w tym to, co zwraca wycofana wartość, warto przeczytać razem z tym procesem w tekście o nagłówku wersji wymaganym przy każdym wywołaniu /rest/.

Czego LinkedIn tu nie dokumentuje?

Trzech rzeczy i w każdej z nich musisz podjąć decyzję bez źródła, na które można się powołać.

Jak długo ważny jest adres przesyłania. W odpowiedzi dostajesz uploadUrlExpiresAt, ale nigdzie na stronie nie ma podanego czasu trwania, więc narzędzie do planowania wysyłające pliki partiami musi traktować znacznik czasu jako jedyną gwarancję.

Czy przed utworzeniem posta trzeba czekać na AVAILABLE. Wartości statusu są udokumentowane, GET, który je zwraca, też, ale związek między nimi a wywołaniem POST /rest/posts już nie. Bezpieczny schemat to odpytywanie aż do AVAILABLE, przy czym jest to schemat, a nie reguła.

Co zrobić z PROCESSING_FAILED. Schemat wymienia przyczyny i na tym poprzestaje. Nie ma udokumentowanego endpointu ponowienia, co w praktyce oznacza nową inicjalizację i nowy URN. Zespoły, które robią to na dużą skalę przez narzędzie do planowania postów na LinkedInie, same budują takie ponawianie, podobnie jak przy innych API publikacji z trzyetapowym procesem multimediów.

Trzy nieudokumentowane decyzje
1
Ważność adresu przesyłania. Czas trwania nie jest podany, więc jedyną gwarancją jest uploadUrlExpiresAt.
2
Czekanie na AVAILABLE. Odpytywanie aż do zmiany statusu to schemat, a nie udokumentowana reguła.
3
PROCESSING_FAILED. Nie ma endpointu ponowienia, więc rozwiązaniem jest nowe wywołanie initializeUpload i nowy URN.
Każdą z tych trzech decyzji podejmujesz bez oparcia w dokumentacji LinkedIna.

Najczęściej zadawane pytania

Czym jest endpoint initializeUpload na LinkedInie?

POST https://api.linkedin.com/rest/images?action=initializeUpload. To akcja w Images API, która rejestruje przesyłanie i zwraca uploadUrl, znacznik czasu uploadUrlExpiresAt oraz URN image, zanim zostaną wysłane jakiekolwiek dane pliku.

Jak wygląda URN obrazu z initializeUpload?

urn:li:image:{id}, na przykład urn:li:image:C4E10AQFoyyAjHPMQuQ. Ten sam identyfikator występuje w ścieżce zwróconego adresu przesyłania, a URN przekazujesz jako content.media.id przy tworzeniu posta.

Jaką metodą HTTP przesyła się obraz na LinkedIna?

PUT. Strona Assets stwierdza "Use a PUT method to upload the image" i wymaga "a valid OAuth token in the 'Authorization' header", a udane przesłanie zwraca 201 z pustą treścią. Tekst przewodnika konsumenckiego mówi o POST, ale jego własny przykład curl używa --upload-file, które wysyła PUT.

AdaptlyPost
AdaptlyPost

Rozpocznij 7-dniowy bezpłatny okres próbny

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Czy przed publikacją trzeba czekać na zakończenie przetwarzania obrazu?

LinkedIn nie dokumentuje obowiązkowego oczekiwania. Dokumentuje pole status obrazu z wartościami WAITING_UPLOAD, PROCESSING, AVAILABLE i PROCESSING_FAILED, a bezpieczną interpretacją jest odpytywanie GET /rest/images/{urn} aż do AVAILABLE.

Dlaczego initializeUpload zwraca 403?

Udokumentowana treść to "Accessing this image resource is forbidden. Please check your permissions for this resource" ze "status": 403. Kontrole uprawnień opierają się na rolach: właściciel z URN firmy wymaga uprawnień ADMIN lub DSC na stronie, a właściciel z URN członka musi być tą samą osobą co wywołujący.

Czy token z samym w_member_social może korzystać z Images API?

Do zapisu tak. LinkedIn podaje, że "w_member_social permission are write-only and tokens with only w_member_social permissions would be unable to perform a GET call for rest/images", więc taki token może zainicjować i przesłać plik, ale nie sprawdzi statusu obrazu w wersjonowanym endpoincie.

Jakie formaty i rozmiary obrazów przyjmuje Images API LinkedIna?

Images API przyjmuje pliki JPG, GIF i PNG o rozmiarze do 36 152 320 pikseli. Pliki GIF mogą mieć do 250 klatek. Limity dotyczą każdego obrazu wysyłanego trzyetapowym procesem, a nie tylko jednego z jego kroków.

Czy Images API LinkedIna obsługuje przesyłanie synchroniczne?

Nie. LinkedIn zaznacza to w ramce: "SYNCHRONOUS_UPLOAD is not supported in Images API." Trzy wywołania, czyli initializeUpload, PUT i POST /rest/posts, to wszystko, co jest dostępne, bez skrótu w jednym wywołaniu, do którego niektórzy przywykli w starszym Assets API.

Jakie zakresy OAuth pozwalają wywoływać Images API LinkedIna?

rw_ads, w_member_social, w_organization_social lub w_power_creators. Każdy z nich wystarcza do initializeUpload i przesłania przez PUT, ale samo w_member_social nie odczyta statusu obrazu przez GET, bo LinkedIn opisuje ten zakres jako przeznaczony wyłącznie do zapisu.

Ile obrazów może zawierać jeden post na LinkedInie?

Post z jednym obrazem odwołuje się do jednego URN przez content.media.id. Post z wieloma obrazami zastępuje to tablicą images, która według LinkedIna musi zawierać od 2 do 20 URN.

Czy ten artykuł był pomocny?

Chętnie poznamy opinię!

Więcej naszych treści w Google

Jedno kliknięcie oznacza AdaptlyPost jako preferowane źródło, dzięki czemu nasze artykuły pojawiają się wyżej w Najważniejszych wiadomościach, trybie AI i Podsumowaniach AI.

Jeszcze chwila...

AdaptlyPost

AdaptlyPost

Planowanie treści na wszystkich platformach

Wszystkie konta społecznościowe w jednym miejscu dzięki AdaptlyPost.

Analityka wszystkich platform

Skrzynka społecznościowa

Asystent oparty na AI

Powiązane hasła ze słownika

Powiązane artykuły