Consulte o ponto de extremidade oEmbed do Instagram para obter um HTML incorporado de uma publicação do Instagram e os metadados básicos para exibi-la em outro site ou app. Compatível com publicações de foto, vídeo, Reel e guia.
Ponto de extremidade | Descrição |
---|---|
Obtenha um HTML incorporado e os metadados básicos de uma publicação do Instagram. |
Para usar o oEmbed, o app precisa passar pela análise para o recurso oEmbed Read.
No campo do formulário em que você fornece uma URL para o teste do oEmbed Read, use o ponto de extremidade oEmbed do Instagram para obter o HTML incorporado de qualquer publicação aberta na nossa Página oficial no Facebook ou no Instagram (ou obtenha o HTML incorporado de qualquer uma das páginas). Adicione o HTML incorporado obtido à página onde o conteúdo oEmbed deverá ser exibido e insira a URL dessa página no campo do formulário.
Depois de receber a aprovação para o recurso oEmbed Read, você poderá incorporar páginas, publicações ou vídeos usando as respectivas URLs.
O ponto de extremidade oEmbed do Instagram requer um token de acesso do app (recomendado) ou um token de acesso do cliente.
Caso seu app dependa de um servidor de back-end, recomendamos que você use o token de acesso do app ao acessar o ponto de extremidade oEmbed. Os limites de volume dependem do tipo de token incluído na solicitação, e os limites de volume do token do app permitem até 5 milhões de solicitações por dia.
Para ver instruções sobre como gerar esses tokens, consulte a seção sobre tokens do app da nossa documentação sobre tokens de acesso.
Lembre-se de que os tokens de acesso do app nunca devem ser usados no lado do cliente. Eles devem ser mantidos em segurança e armazenados no seu servidor. Se o app precisar usar um token no lado do cliente, use um token de acesso do cliente.
Caso o app precise acessar o ponto de extremidade oEmbed a partir de um agente do usuário (como um dispositivo móvel ou um navegador da web), o app deverá usar um token de acesso do cliente e estará sujeito aos limites de volume correspondentes.
Para obter um token de acesso do cliente, entre no Painel de Apps e navegue até Configurações > Avançado > Segurança > Token de cliente.
Ao contrário dos tokens de acesso do app, os tokens de acesso do cliente não podem ser usados em solicitações do ponto de extremidade oEmbed sozinhos. Eles devem ser combinados com o ID do app. Para fazer isso, adicione seu token ao final do ID do app, separado por um símbolo de barra (|
):
{app-id}|{client-token}
Por exemplo:
access_token=1234|5678
Os limites de volume dependem do tipo de token de acesso que seu app inclui em cada solicitação.
Os apps que dependem de tokens de acesso do app podem fazer até 5 milhões de solicitações em 24 horas.
Os limites de volume do token de cliente são significativamente mais baixos em comparação aos do token do app. Não revelamos o limite real, pois ele mudará dependendo da atividade do app. Contudo, você pode supor com segurança que seu app não alcançará o limite a menos que ele exiba um comportamento similar a um bot, como fazer milhares de solicitações em lote ou enviar milhares de solicitações por agente ou usuário.
Para obter o HTML incorporado de uma publicação do Instagram, envie uma solicitação para:
GET /instagram_oembed?url={url}&access_token={access-token}
Substitua {url}
pela URL da publicação do Instagram que você deseja consultar e {access-token}
pelo seu token de acesso do cliente ou app (ou transmita-o para nós em um cabeçalho HTTP). Se estiver usando um token de acesso do cliente, lembre-se de que você deve combiná-lo com o ID do app usando um símbolo de barra, do contrário, a solicitação falhará.
Caso a solicitação seja bem-sucedida, a API responderá com um objeto JSON contendo o HTML incorporado da publicação e dados adicionais. O HTML incorporado será atribuído à propriedade html
.
Consulte a referência do oEmbed do Instagram para ver uma lista dos parâmetros da string de consulta que você pode incluir para aumentar a solicitação. Além disso, é possível incluir o parâmetro da string de consulta fields
para especificar os campos que você deseja que sejam retornados. Caso ele seja omitido, todos os campos padrão serão incluídos na resposta.
curl -X GET \
"https://graph.facebook.com/v20.0
/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."
Alguns valores foram reduzidos com reticências (...
) para facilitar a leitura.
{ "version": "1.0", "author_name": "diegoquinteiro", "provider_name": "Instagram", "provider_url": "https://www.instagram.com/", "type": "rich", "width": 658, "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...", "thumbnail_width": 640, "thumbnail_height": 640 }
O parâmetro da string de consulta url
aceita os seguintes formatos de URL:
https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/
https://www.instagram.com/{username}/guide/{slug}/{guide_id}
O HTML incorporado contém uma referência à biblioteca de JavaScript embed.js do Instagram. Quando carregar, a biblioteca buscará o HTML da publicação na página e gerará a publicação renderizada. Se você quiser carregar a biblioteca separadamente, inclua o parâmetro da string de consulta omitscript=true
na solicitação. Para inicializar manualmente o HTML incorporado, chame a função instgrm.Embeds.process()
depois de carregar a biblioteca.
A publicação incorporada é responsiva e se adapta ao tamanho do contêiner. Isso significa que a altura variará dependendo da largura do contêiner e do comprimento da legenda. Você pode definir a largura máxima incluindo o parâmetro da string de consulta maxwidth
na solicitação.
Recomendamos que você renderize todo o HTML incorporado da publicação sempre que possível. Se você não conseguir fazer isso, pode obter a URL da imagem de miniatura de uma publicação e renderizá-la. No entanto, se fizer isso, você precisará informar a atribuição de modo claro próxima à imagem, incluindo a atribuição ao autor original e ao Instagram, além de um link para a publicação do Instagram que está consultando.
Para obter a URL da miniatura e a atribuição de uma publicação, envie uma solicitação para:
GET /instagram_oembed ?url={url} &maxwidth={maxwidth} &fields=thumbnail_url,author_name,provider_name,provider_url &access_token={access-token}
Substitua {url}
pela URL da publicação do Instagram que você quer consultar, {maxwidth}
pelo tamanho máximo da miniatura que deseja renderizar e {access-token}
pelo seu token de acesso do cliente ou app.
curl -i -X GET \
"https://graph.facebook.com/v20.0
/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."
Alguns valores foram reduzidos com reticências (...
) para facilitar a leitura.
{ "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...", "author_name": "diegoquinteiro", "provider_name": "Instagram", "provider_url": "https://www.instagram.com/" }
Se você não quiser incluir seu token de acesso na string de consulta da solicitação, transmita-o para nós por meio de um cabeçalho HTTP Authorization
.
Authorization: Bearer {access-token}
Por exemplo:
curl -i -X GET \
"https://graph.facebook.com/v20.0
/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN" \
--header "Authorization: Bearer 96481..."