Prześlij filmy

YouTubeVideoUploadService umożliwia przesyłanie filmów bezpośrednio do YouTube za pomocą interfejsu Google Ads API. Te filmy mogą być następnie używane jako komponenty w różnych typach reklam, np. w kampaniach Performance Max lub kampaniach generujących popyt.

Ta usługa upraszcza proces tworzenia reklam wideo, ponieważ zajmuje się przesyłaniem filmów do YouTube i zapewnia, że są one prawidłowo powiązane z Twoim kontem.

Kluczowych pojęć

Zanim zaczniesz, dowiedz się, jak zarządza się przesyłaniem filmów i jakie stany mogą one przyjmować.

Własność kanału

Podczas przesyłania filmu możesz określić docelowy kanał w YouTube za pomocą pola channel_id w zasobie YouTubeVideoUpload:

  • Kanał należący do reklamodawcy (marki): podaj channel_id kanału YouTube należącego do reklamodawcy. Przesyłanie na kanał marki daje większą kontrolę nad prywatnością i widocznością filmu.
  • Kanał zarządzany przez Google: jeśli symbol channel_id zostanie pominięty, film zostanie przesłany na kanał w YouTube zarządzany przez Google, który jest powiązany z kontem Google Ads.

Stany przesyłania

Cykl życia przesłanego filmu w YouTube jest śledzony przez pole state. Wyliczenie YouTubeVideoUploadState określa te stany:

Stan Opis
PENDING Trwa przesyłanie filmu.
UPLOADED Film został przesłany i jest przetwarzany przez YouTube.
PROCESSED Film został przetworzony i jest gotowy do użycia.
FAILED Przesyłanie lub przetwarzanie nie powiodło się i nie można go ukończyć.
REJECTED Film został odrzucony z powodu weryfikacji lub zasad.
UNAVAILABLE Stan filmu jest niedostępny. Mógł zostać usunięty z YouTube.

Ustawienia prywatności

Pole video_privacy określa, kto może zobaczyć przesłany film. Wyliczenie YouTubeVideoPrivacy obsługuje:

  • PUBLIC: film jest dostępny dla wszystkich użytkowników YouTube. (Dozwolone tylko w przypadku kanałów marek).
  • UNLISTED: film nie jest dostępny w wyszukiwarce, ale może go obejrzeć każdy, kto ma link. Jest to domyślna i jedyna opcja w przypadku kanałów zarządzanych przez Google.

Prześlij film

Aby przesłać film, musisz użyć żądania wieloczęściowego do metody CreateYouTubeVideoUpload. Żądanie zawiera zarówno metadane przesyłanego pliku, jak i sam plik wideo.

1. Rozpocznij przesyłanie

Utwórz CreateYouTubeVideoUploadRequest, podając:

  • customer_id: Twój identyfikator klienta Google Ads.
  • you_tube_video_upload: obiekt YouTubeVideoUpload z właściwościami video_title, video_description i opcjonalnie channel_id oraz video_privacy.

Jeśli używasz biblioteki klienta, wywołaj metodę CreateYouTubeVideoUpload przekazując plik wideo. Przesyłanie filmu zostanie obsłużone wewnętrznie.

Java

This example is not yet available in Java; you can take a look at the other languages.

C#

This example is not yet available in C#; you can take a look at the other languages.

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

yt_service: YouTubeVideoUploadServiceClient = client.get_service(
    "YouTubeVideoUploadService"
)

create_upload_request: CreateYouTubeVideoUploadRequest = (
    youtube_video_upload_service.CreateYouTubeVideoUploadRequest()
)
create_upload_request.customer_id = customer_id
create_upload_request.you_tube_video_upload.video_title = "Test Video"
create_upload_request.you_tube_video_upload.video_description = (
    "Test Video Description"
)
create_upload_request.you_tube_video_upload.video_privacy = (
    client.enums.YouTubeVideoPrivacyEnum.UNLISTED
)

video_upload_resource_name: str
with open(video_file_path, "rb") as stream:
    response: CreateYouTubeVideoUploadResponse = (
        yt_service.create_you_tube_video_upload(
            stream=stream,
            request=create_upload_request,
            retry=None,
        )
    )
    print(f"Created YouTube video upload: {response.resource_name}")
upload_video.py

Ruby

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

curl

# 
# Use the --i curl parameter to capture response headers in the $RESPONSE
# variable.
FILE_SIZE=$(wc -c < "${VIDEO_FILE_NAME}" | tr -d '\r')
RESPONSE=$(curl -i -f -v -s --request POST \
"https://googleads.googleapis.com/resumable/upload/v${API_VERSION}/customers/${CUSTOMER_ID}:youTubeVideoUploads:create" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--header "X-Goog-Upload-Protocol: resumable" \
--header "X-Goog-Upload-Command: start" \
--header "X-Goog-Upload-Header-Content-Length: ${FILE_SIZE}" \
--data @- <<EOF
{
  "customer_id": "${CUSTOMER_ID}",
  "you_tube_video_upload": {
    "video_title": "${VIDEO_TITLE}",
    "video_description": "${VIDEO_DESCRIPTION}",
    "video_privacy": "UNLISTED"
  }
}
EOF
)

# Extract the value of the "x-goog-upload-url" header from the HTTP response.
UPLOAD_URL=$(echo "${RESPONSE}" \
  | grep -i '^x-goog-upload-url' \
  | awk '{print $2}' \
  | tr -d '\r')
CHUNK_SIZE=$(echo "${RESPONSE}" \
  | grep -i '^x-goog-upload-chunk-granularity' \
  | awk '{print $2}' \
  | tr -d '\r')
upload_video.sh

Jeśli używasz interfejsu REST, w sekcji poniżej znajdziesz opis zarządzania przesyłaniem filmów.

2. Prześlij film

Gdy wyślesz żądanie REST do metody CreateYouTubeVideoUpload, odpowiedź będzie zawierać adres URL, który ma być używany do przesyłania bajtów wideo, w nagłówku odpowiedzi HTTP x-goog-upload-url, a także inne metadane, takie jak oczekiwany rozmiar każdego fragmentu w przypadku przesyłania fragmentów.

Możesz też zadeklarować rozmiar filmu, który zamierzasz przesłać, na początku procesu, używając nagłówka żądania HTTP x-goog-upload-header-content-length.

Pełny opis nagłówków HTTP używanych w protokole przesyłania filmów znajdziesz w tym przykładzie kodu:

# Take the first ${CHUNK_SIZE} bytes of the video file and upload them.
head -c ${CHUNK_SIZE} ${VIDEO_FILE_NAME} | curl -i -v -X PUT "${UPLOAD_URL}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--header "X-Goog-Upload-Offset: 0" \
--header "X-Goog-Upload-Command: upload" \
--header "Content-Length: ${CHUNK_SIZE}" \
--data-binary @-

# Query the status of the upload.
QUERY_RESPONSE=$(curl -i -s -X POST "${UPLOAD_URL}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--header "X-Goog-Upload-Command: query")

# Extract the value of the "x-goog-upload-size-received" header from the HTTP
# response.
UPLOADED_BYTES=$(echo "${QUERY_RESPONSE}" \
  | grep -i '^x-goog-upload-size-received' \
  | awk '{print $2}' \
  | tr -d '\r')

echo "Uploaded ${UPLOADED_BYTES} bytes."

REMAINING_BYTES=$((FILE_SIZE - UPLOADED_BYTES))
echo "${REMAINING_BYTES} bytes remaining to upload."

FINALIZE_RESPONSE=$(tail -c ${REMAINING_BYTES} ${VIDEO_FILE_NAME} | curl -v -X PUT "${UPLOAD_URL}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--header "X-Goog-Upload-Offset: ${UPLOADED_BYTES}" \
--header "X-Goog-Upload-Command: upload, finalize" \
--data-binary @-)
UPLOADED_VIDEO_RESOURCE_NAME=$(echo $FINALIZE_RESPONSE | jq -r '.resourceName')
upload_video.sh

3. Pobieranie stanu przesyłania filmu

Po rozpoczęciu przesyłania filmu możesz pobrać jego stan, wysyłając zapytanie do zasobu you_tube_video_upload za pomocą GAQL:

Java

This example is not yet available in Java; you can take a look at the other languages.

C#

This example is not yet available in C#; you can take a look at the other languages.

PHP

This example is not yet available in PHP; you can take a look at the other languages.

Python

# Retrieve the metadata of the newly uploaded video.
query: str = f"""
    SELECT
      you_tube_video_upload.resource_name,
      you_tube_video_upload.video_id,
      you_tube_video_upload.state
    FROM you_tube_video_upload
    WHERE you_tube_video_upload.resource_name = '{video_upload_resource_name}'"""

ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")
stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
    customer_id=customer_id, query=query
)

for row in itertools.chain.from_iterable(batch.results for batch in stream):
    video = row.you_tube_video_upload
    print(
        f"Video with ID {row.you_tube_video_upload.video_id} was found in state {row.you_tube_video_upload.state}."
    )
upload_video.py

Ruby

This example is not yet available in Ruby; you can take a look at the other languages.

Perl

This example is not yet available in Perl; you can take a look at the other languages.

curl

curl -i -v -X POST \
"https://qa-prod-googleads.sandbox.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--header "Content-Type: application/json" \
  --header "Developer-Token: ${DEVELOPER_TOKEN}" \
  --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
  --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
  --data @- <<EOF
{
  "query": "SELECT you_tube_video_upload.resource_name, you_tube_video_upload.video_id, you_tube_video_upload.state FROM you_tube_video_upload WHERE you_tube_video_upload.resource_name = '$UPLOADED_VIDEO_RESOURCE_NAME'"
}
EOF
upload_video.sh

Zarządzaj przesyłaniem

Po przesłaniu filmu możesz go używać jako zasobu wideo.

Używanie przesłanego filmu

Gdy film osiągnie stan PROCESSED, jego identyfikator w YouTube znajdziesz w polu video_id zasobu YouTubeVideoUpload.

Użyj tego video_id, aby utworzyć VideoAsset lub połączyć go bezpośrednio z typami reklam, które obsługują filmy w YouTube, odwołując się do identyfikatora filmu.

Zaktualizuj metadane

Metadane filmu przesłanego za pomocą tego interfejsu API możesz zaktualizować za pomocą metody UpdateYouTubeVideoUpload. Można aktualizować tylko pola video_title, video_description i video_privacy.

Usuwanie przesłanych plików

Jeśli chcesz usunąć filmy przesłane za pomocą interfejsu Google Ads API, użyj metody RemoveYouTubeVideoUpload. Spowoduje to usunięcie filmu zarówno z biblioteki komponentów Google Ads, jak i z YouTube.

Wstecz
Komponenty do wysyłania wiadomości do firmy
Dalej
Raportowanie