Prześlij filmy

YouTubeVideoUploadService umożliwia przesyłanie filmów bezpośrednio do YouTube za pomocą interfejsu Google Ads API. Te filmy można następnie wykorzystać do tworzenia komponentów wideo w różnych typach reklam, np. w kampaniach Performance Max lub kampaniach generujących popyt.

Ta usługa upraszcza proces tworzenia reklam wideo, ponieważ obsługuje proces przesyłania do YouTube i zapewnia prawidłowe powiązanie filmów z Twoim kontem.

Kluczowe pojęcia

Zanim zaczniesz, musisz zrozumieć, 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ł YouTube za pomocą pola channel_id w YouTubeVideoUpload zasobie:

  • Kanał należący do reklamodawcy (marki): podaj channel_id istniejącego kanału YouTube należącego do reklamodawcy. Jest to obsługiwane tylko w przypadku procesu uwierzytelniania użytkownika; nie można go używać z kontami usługi.
  • Kanał zarządzany przez Google: jeśli pole channel_id zostanie pominięte, film zostanie przesłany na kanał YouTube zarządzany przez Google, który jest powiązany z kontem Google Ads.

Stany przesyłania

Cykl życia przesyłania filmu na YouTube jest śledzony przez pole state. Wyliczenie YouTubeVideoUploadState definiuje 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 naruszenia zasad.
UNAVAILABLE Stan filmu jest niedostępny. Film 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 te opcje:

  • PUBLIC: film jest dostępny dla wszystkich użytkowników YouTube. (Dozwolone tylko w przypadku kanałów firmowych).
  • UNLISTED: film nie jest widoczny w wynikach wyszukiwania, ale mogą go wyświetlać osoby, które mają do niego link. Jest to opcja domyślna i jedyna dostępna w przypadku kanałów zarządzanych przez Google.

Informowanie o treściach wygenerowanych przez AI

Począwszy od wersji 26, zgodnie z przepisami, takimi jak akt (UE) w sprawie sztucznej inteligencji, reklamodawcy mogą ujawniać, czy przesłane treści wideo zawierają media wygenerowane przez AI lub syntetyczne.

Pole video_content_metadata w YouTubeVideoUpload zawiera VideoContentMetadata. Ustaw jego zagnieżdżone generative_content_disclosure pole za pomocą YouTubeVideoUploadGenerativeContentDisclosure wyliczenia:

Wartość Opis
NON_GENERATIVE_CONTENT Reklamodawca poinformował, że film nie został wygenerowany przez AI.
GENERATIVE_CONTENT Reklamodawca poinformował, że film został wygenerowany przez AI.

Prześlij film

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

1. Rozpocznij przesyłanie

Utwórz CreateYouTubeVideoUploadRequest określając:

  • customer_id: Twój identyfikator klienta Google Ads.
  • you_tube_video_upload: obiekt YouTubeVideoUpload z polami video_title, video_description oraz opcjonalnie channel_id, video_privacy i od wersji 26 video_content_metadata.

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#

YouTubeVideoUploadServiceClient ytService = client.GetService(
    Services.V25.YouTubeVideoUploadService);

CreateYouTubeVideoUploadRequest createUploadRequest =
    new CreateYouTubeVideoUploadRequest()
    {
        CustomerId = customerId.ToString(),
        YouTubeVideoUpload = new YouTubeVideoUpload()
        {
            VideoTitle = "Test Video",
            VideoDescription = "Test Video Description",
            VideoPrivacy = YouTubeVideoPrivacy.Unlisted
        }
    };

string videoUploadResourceName;
using (FileStream stream = File.OpenRead(videoFilePath))
{
    ResumableUploadSession<CreateYouTubeVideoUploadRequest, CreateYouTubeVideoUploadResponse> session =
        ytService.CreateYouTubeVideoUpload();
    CreateYouTubeVideoUploadResponse response =
        session.BeginUploadAsync(createUploadRequest, stream).Result;

    videoUploadResourceName = response.ResourceName;
    Console.WriteLine($"Created YouTube video upload: {videoUploadResourceName}");
}
      

PHP

$youTubeVideoUploadServiceClient = $googleAdsClient->getYouTubeVideoUploadServiceClient();

$youTubeVideoUpload = new YouTubeVideoUpload([
    'video_title' => 'Test Video',
    'video_description' => 'Test Video Description',
    'video_privacy' => YouTubeVideoPrivacy::UNLISTED
]);

$createYouTubeVideoUploadRequest = CreateYouTubeVideoUploadRequest::build(
    $customerId,
    $youTubeVideoUpload
);

/** @var ResumableUpload $resumableUpload */
$resumableUpload = $youTubeVideoUploadServiceClient->createYouTubeVideoUpload(
    $createYouTubeVideoUploadRequest
);

$stream = Utils::streamFor(fopen($videoFilePath, 'rb'));
/** @var CreateYouTubeVideoUploadResponse $response */
$response = $resumableUpload->startUpload($stream);

$videoUploadResourceName = $response->getResourceName();
printf("Created YouTube video upload: '%s'%s", $videoUploadResourceName, PHP_EOL);
      

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,
        )
    )
    video_upload_resource_name = response.resource_name
    print(f"Created YouTube video upload: {video_upload_resource_name}")
      

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 "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')
      

Jeśli używasz REST, w tej sekcji opisujemy, jak zarządzać przesyłaniem filmu.

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 filmu w nagłówku odpowiedzi HTTP x-goog-upload-url, oraz inne metadane, takie jak oczekiwany rozmiar każdego fragmentu w przypadku przesyłania fragmentowego, zgodnie ze standardowym protokołem przesyłania z możliwością wznowienia Google .

Możesz też zadeklarować rozmiar przesyłanego filmu na początku procesu za pomocą 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')
      

3. Pobierz stan przesyłania filmu

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

Java

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

C#

// Retrieve the metadata of the newly uploaded video.
string 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 = '{videoUploadResourceName}'";

GoogleAdsServiceClient gaService = client.GetService(
    Services.V25.GoogleAdsService);

gaService.SearchStream(customerId.ToString(), query,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow row in resp.Results)
        {
            Console.WriteLine(
                $"Video with ID {row.YouTubeVideoUpload.VideoId} was found in " +
                $"state {row.YouTubeVideoUpload.State}.");
        }
    }
);
      

PHP

// Retrieve the metadata of the newly uploaded video.
$query = sprintf(
    "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 = '%s'",
    $videoUploadResourceName
);

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$stream = $googleAdsServiceClient->searchStream(
    SearchGoogleAdsStreamRequest::build($customerId, $query)
);

foreach ($stream->iterateAllElements() as $googleAdsRow) {
    /** @var GoogleAdsRow $googleAdsRow */
    printf(
        "Video with ID '%s' was found in state '%s'.%s",
        $googleAdsRow->getYouTubeVideoUpload()->getVideoId(),
        YouTubeVideoUploadState::name($googleAdsRow->getYouTubeVideoUpload()->getState()),
        PHP_EOL
    );
}
      

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}."
    )
      

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
      

Zarządzaj przesyłaniem

Po zakończeniu przesyłania filmu możesz go używać jako komponentu wideo.

Użyj przesłanego filmu

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

Użyj tego video_id, aby utworzyć YoutubeVideoAsset za pomocą MutateAssets lub połączyć go bezpośrednio z typami reklam, które obsługują filmy na 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 zaktualizować tylko pola video_title, video_description i video_privacy.

Usuń przesłane pliki

Jeśli musisz 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.