Class: X::Media

Inherits:

Resource

• Object
• Resource
• X::Media

Extended by:

BatchFinders, Resources::BatchFinders

Defined in:

x-resources/lib/x/resources/media.rb

Overview

A photo, video, or animated GIF attached to a post, which its media key identifies

Constant Summary

FIELDS =

Every public media field

A minor release may add to it the fields the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of fields of its own.

%w[alt_text duration_ms height media_key preview_image_url public_metrics type url variants width].freeze

Instance Attribute Summary

• #alt_text ⇒ String^? readonly

  The alternative text.

• #duration_ms ⇒ Integer^? readonly

  The duration of a video in milliseconds.

• #height ⇒ Integer^? readonly

  The height in pixels.

• #media_key ⇒ String readonly

  The media key.

• #preview_image_url ⇒ String^? readonly

  The URL of a video or GIF preview image.

• #public_metrics ⇒ Hash^? readonly

  The public metrics.

• #type ⇒ String^? readonly

  The media type: photo, video, or animated_gif.

• #url ⇒ String^? readonly

  The URL of a photo.

• #variants ⇒ Array<Hash> readonly

  The video variants with their bit rates, content types, and URLs.

• #view_count ⇒ Integer^? readonly

  The number of views.

• #width ⇒ Integer^? readonly

  The width in pixels.

Class Method Summary

• .default_params ⇒ Hash{String => Array<String>}

  The default query parameters requesting every public field.

• .find(media, client:, **params) {|problem| ... } ⇒ Media^?

  Look up media by media key.

• .find!(media, client:, **params) ⇒ Media

  Look up media by media key, which must exist.

• .find_all(media, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Media>

  Look up many media by media key, in parallel batches.

• .from_id(media, client: nil) ⇒ Media

  Refer to media by media key without a request.

• .hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Resource> extended from Resources::BatchFinders

  Replace the resources that are not hydrated with the full resources.

Instance Method Summary

• #id ⇒ String

  The identifier of the media, which is its media key.

• #media_id ⇒ Integer

  The numeric identifier of the media, which its media key names.

Constructor Details

This class inherits a constructor from X::Resource

Instance Attribute Details

#alt_text ⇒ String^? (readonly)

The alternative text

Examples:

Get the alternative text

media.alt_text

Returns:

• (String, nil) —

  the alternative text

# File 'x-resources/lib/x/resources/media.rb', line 227

attribute :alt_text

#duration_ms ⇒ Integer^? (readonly)

The duration of a video in milliseconds

Examples:

Get the duration

media.duration_ms

Returns:

• (Integer, nil) —

  the duration in milliseconds

# File 'x-resources/lib/x/resources/media.rb', line 235

attribute :duration_ms, :integer

#height ⇒ Integer^? (readonly)

The height in pixels

Examples:

Get the height

media.height

Returns:

• (Integer, nil) —

  the height in pixels

# File 'x-resources/lib/x/resources/media.rb', line 243

attribute :height, :integer

#media_key ⇒ String (readonly)

The media key

Examples:

Get the media key

media.media_key

Returns:

• (String) —

  the media key

# File 'x-resources/lib/x/resources/media.rb', line 184

attribute :media_key

#preview_image_url ⇒ String^? (readonly)

The URL of a video or GIF preview image

Examples:

Get the preview image URL

media.preview_image_url

Returns:

• (String, nil) —

  the preview image URL

# File 'x-resources/lib/x/resources/media.rb', line 219

attribute :preview_image_url

#public_metrics ⇒ Hash^? (readonly)

The public metrics

Examples:

Get the public metrics

media.public_metrics

Returns:

• (Hash, nil) —

  the public metrics

# File 'x-resources/lib/x/resources/media.rb', line 267

attribute :public_metrics, :object

#type ⇒ String^? (readonly)

The media type: photo, video, or animated_gif

Examples:

Get the type

media.type

Returns:

• (String, nil) —

  the media type

# File 'x-resources/lib/x/resources/media.rb', line 203

attribute :type

#url ⇒ String^? (readonly)

The URL of a photo

Examples:

Get the URL

media.url

Returns:

• (String, nil) —

  the URL

# File 'x-resources/lib/x/resources/media.rb', line 211

attribute :url

#variants ⇒ Array<Hash> (readonly)

The video variants with their bit rates, content types, and URLs

Examples:

Get the variants

media.variants

Returns:

• (Array<Hash>) —

  the variants, empty if there are none

# File 'x-resources/lib/x/resources/media.rb', line 259

attribute :variants, :objects

#view_count ⇒ Integer^? (readonly)

The number of views

Examples:

Get the view count

media.view_count

Returns:

• (Integer, nil) —

  the view count

# File 'x-resources/lib/x/resources/media.rb', line 275

attribute :view_count, :integer, key: %w[public_metrics view_count]

#width ⇒ Integer^? (readonly)

The width in pixels

Examples:

Get the width

media.width

Returns:

• (Integer, nil) —

  the width in pixels

# File 'x-resources/lib/x/resources/media.rb', line 251

attribute :width, :integer

Class Method Details

.default_params ⇒ Hash{String => Array<String>}

The default query parameters requesting every public field

Examples:

Get the default fields

X::Media.default_params["media.fields"]

Returns:

• (Hash{String => Array<String>}) —

  the default query parameters

# File 'x-resources/lib/x/resources/media.rb', line 67

def self.default_params
  {"media.fields" => FIELDS}
end

.find(media, client:, **params) {|problem| ... } ⇒ Media^?

Look up media by media key

Examples:

Look up what an upload returned

X::Media.find(uploaded, client: client)

Parameters:

• media (#media_key, String, Media) —

  the media key, what an upload returned, or media

• client (Object) —

  the client used to make the request

• params (Hash) —

  query parameters merged over the default parameters

Yield Parameters:

• problem (Problem) —

  each problem the API reported

Returns:

• (Media, nil) —

  the media, or nil if it was not found

# File 'x-resources/lib/x/resources/media.rb', line 105

def self.find(media, client:, **params) = super(key_of(media), client:, **params) #: Media?

.find!(media, client:, **params) ⇒ Media

Look up media by media key, which must exist

The error it raises names the media key looked up, whether a media key, what an upload returned, or media was given.

Examples:

Look up what an upload returned

X::Media.find!(uploaded, client: client)

Parameters:

• media (#media_key, String, Media) —

  the media key, what an upload returned, or media

• client (Object) —

  the client used to make the request

• params (Hash) —

  query parameters merged over the default parameters

Returns:

• (Media) —

  the media

Raises:

• (MissingResource) —

  if the media was not found

# File 'x-resources/lib/x/resources/media.rb', line 120

def self.find!(media, client:, **params) = super(key_of(media), client:, **params) #: Media

.find_all(media, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Media>

Look up many media by media key, in parallel batches

Examples:

Look up what the uploads returned

X::Media.find_all(uploads, client: client)

Parameters:

• media (Array<#media_key, String, Media>) —

  the media keys, what the uploads returned, or media

• client (Object) —

  the client used to make the requests

• params (Hash) —

  query parameters merged over the default parameters, and the concurrency of the batches

Yield Parameters:

• problem (Problem) —

  each problem the API reported

Returns:

• (Array<Media>) —

  the media that was found

# File 'x-resources/lib/x/resources/media.rb', line 153

def self.find_all(media, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) = super(media.map { |value| key_of(value) }, client:, concurrency:, **params) #: Array[Media]

.from_id(media, client: nil) ⇒ Media

Refer to media by media key without a request

Examples:

Refer to what an upload returned

X::Media.from_id(uploaded, client: client).hydrate.url

Parameters:

• media (#media_key, String, Media) —

  the media key, what an upload returned, or media

• client (Object, nil) (defaults to: nil) —

  the client used to fetch the media

Returns:

• (Media) —

  a stub that hydrates to the full media

# File 'x-resources/lib/x/resources/media.rb', line 130

def self.from_id(media, client: nil) = super #: Media

.hydrate_all(resources, client:, concurrency: DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Resource> Originally defined in module Resources::BatchFinders

Replace the resources that are not hydrated with the full resources

A resource that hydrate would look up is looked up, which is a stub and also a resource a response included without every field, so what comes back is hydrated throughout. A resource that was not found is dropped, as is nil, which a reference to no resource reads as, such as the author of a post whose response named none, and a hydrated resource is kept as it is, so resources that are all hydrated need no lookup. What was found is stored in each original, so hydrating one of them afterwards costs no request, unless params override a default field or expansion parameter: what such a lookup found is not the full resource, so it is returned without being stored, and hydrating an original fetches the full resource. A resource that holds what hydrate returns, because hydrate or an earlier hydrate_all stored it, is replaced with that, and looked up again by no request, since the API bills each resource a lookup returns.

Examples:

Look up every field of the authors of posts, the ones a search included among them

X::User.hydrate_all(posts.map(&:author), client: client)

Expand only the authors a search did not include, which the API bills for alone

X::User.hydrate_all(posts.filter_map(&:author).select(&:stub?), client: client)

Parameters:

• resources (Array<Resource, nil>) —

  the resources, some of which may not be hydrated, and some nil

• client (Object) —

  the client used to make the requests

• concurrency (Integer) (defaults to: DEFAULT_CONCURRENCY) —

  the number of batch lookups made at once, four by default, which must be at least one

• params (Hash) —

  query parameters merged over the default parameters; one that overrides a default field or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest

Yield Parameters:

• problem (Problem) —

  each problem the API reported, such as a resource that was not found

Returns:

• (Array<Resource>) —

  the resources, in order, with the ones that were not hydrated replaced, frozen

Raises:

• (ArgumentError) —

  if the concurrency is less than one

• (ArgumentError) —

  if a resource is not of this class, which a lookup of its identifier would find another resource for, before a request

Instance Method Details

#id ⇒ String

The identifier of the media, which is its media key

Media is looked up by its media key, so that is what identifies it here, where the identifier of uploaded media, and the one a post or a direct message attaches media by, is the number media_id reads. Both X::Media and the uploaded media of x-uploads answer media_key and media_id alike.

Examples:

Get the media key

media.id # => "3_1880028106020515840"

Returns:

• (String) —

  the media key

# File 'x-resources/lib/x/resources/media.rb', line 166

#media_id ⇒ Integer

The numeric identifier of the media, which its media key names

A media key names the identifier after the number of the type of the media and an underscore. It is the identifier an upload returns, and the one a post or a direct message attaches media by.

Examples:

Get the identifier the media key names

X::Media.from_id("3_1880028106020515840").media_id # => 1880028106020515840

Returns:

• (Integer) —

  the media identifier

# File 'x-resources/lib/x/resources/media.rb', line 195

def media_id = Integer(MediaIds.media_key_id(self), 10)