Utilizar a API REST para atualizar os Suplementos do Microsoft Edge

Utilize esta API REST para atualizar programaticamente uma extensão publicada no site suplementos do Microsoft Edge para automatizar o processo de carregamento e publicação de novas versões da sua extensão. Pode integrar estes pontos finais da API REST diretamente no pipeline de integração/entrega contínua (CI/CD) para publicar atualizações de pacotes de extensões no site de Suplementos do Microsoft Edge sem utilizar o Centro de Parceiros.

Esta API REST expõe pontos finais para:

• Carregar um pacote para atualizar uma submissão existente
• Verificar a status de um carregamento de pacote
• Publicar a submissão
• Verificar o status de publicação

Estes pontos finais são descritos abaixo.

Para utilizar esta API REST, utilize primeiro a página Publicar API no Centro de Parceiros para ativar a API.

Para publicar inicialmente uma nova extensão, utilize o Centro de Parceiros. Para atualizar a extensão, utilize manualmente o Centro de Parceiros ou utilize programaticamente esta API REST.

Para submeter sugestões e comentários, introduza um Problema sobre a API de Suplementos.

Versões da API REST de Atualização

A partir de 6 de setembro de 2024, a v1.1 e a v1 desta API REST de Atualização são suportadas. O suporte para v1 terminará a 31 de dezembro de 2024.

Componentes utilizados

v1.1

v1.1 utiliza uma chave de API. A IU no Centro de Parceiros fornece chaves de API.

Os pontos finais REST utilizam cabeçalhos de pedido específicos para v1.1.

v1

V1 requer o envio de um token de acesso para o ponto final da API. Obtém o token de acesso ao enviar uma mensagem POST para um URL de token de acesso. A IU do Centro de Parceiros mostra o URL do token de acesso.

V1 utiliza Segredos. A IU no Centro de Parceiros fornece Segredos.

Os pontos finais REST utilizam cabeçalhos de pedido específicos para v1.

Descrição geral da utilização da API REST de Atualização

Para utilizar a API REST de Atualização:

v1.1

1. No programador do Centro de Parceiros dashboard, opte ativamente por participar na IU que utiliza chaves de API ao clicar no botão Ativar junto para ativar a nova experiência. Os detalhes estão em Ativar a API REST de Atualização no Centro de Parceiros, abaixo.

2. Anote o ID de Cliente e a nova chave de API.

3. Atualize os fluxos de trabalho de autenticação, se necessário.

4. Configure novamente todos os pipelines de integração/entrega contínua (CI/CD) que possam ser afetados por quaisquer alterações à chave de API, como, por exemplo, se estiver a alterar a utilização da v1 desta API REST, que utiliza tokens de acesso em vez de chaves de API.

5. Quando utiliza um ponto final REST, especifique o ClientID e a chave de API no cabeçalho do pedido. Os detalhes estão em Utilizar os pontos finais da API, abaixo.

v1

1. No programador do Centro de Parceiros dashboard, obtenha um token de acesso a partir do URL do token de acesso. Os detalhes estão em Ativar a API REST de Atualização no Centro de Parceiros, abaixo.

2. Gere o seu ClientID e segredos. Pode gerar vários segredos de cliente para o ID de Cliente. Por exemplo, pode criar múltiplos segredos para vários projetos.

3. Atualize os fluxos de trabalho de autenticação, se necessário.

4. Configure novamente todos os pipelines de integração contínua/entrega contínua (CI/CD) existentes que possam ser afetados pelas alterações ao URL do token de acesso.

5. Obter o token de acesso. Os detalhes estão em Obter o token de acesso, abaixo.

6. Quando utiliza um ponto final REST, especifique o token de acesso no cabeçalho do pedido. Os detalhes estão em Utilizar os pontos finais da API, abaixo.

Os detalhes encontram-se abaixo.

Terminologia

Termo	Definição
operação	Uma operação REST, como GET ou POST.
ID da operação	O ID de uma operação REST.
package	O .zip pacote que contém os ficheiros do suplemento do Microsoft Edge.
produto	Uma extensão ou tema do Microsoft Edge. Também referido como um Suplemento do Microsoft Edge.
ID do produto	O ID do produto cujo rascunho tem de ser publicado. O ID do produto é um GUID de 128 bits associado a um produto no Centro de Parceiros. Por exemplo: d34f98f5-f9b7-42b1-bebb-98707202b21d.
submissão	Uma atualização que está a ser submetida a um produto existente no Centro de Parceiros. Cada atualização de um produto é uma submissão, independentemente de o status ser In Draft, In Reviewou In the Store (publicado).

Ativar a API REST de Atualização no Centro de Parceiros

Para utilizar a API de Suplementos do Microsoft Edge, primeiro tem de ativar a API para o seu projeto no Centro de Parceiros da Microsoft ao criar credenciais de API da seguinte forma:

v1.1

1. No programador do Centro de Parceiros dashboard, inicie sessão na conta que utilizou para publicar um suplemento.

2. No programa Microsoft Edge , selecione Publicar API.

3. Junto à mensagem "ativar a nova experiência", clique no botão Ativar :

   

   A captura de ecrã acima mostra a IU v1, incluindo o URL do token de acesso e segredos, antes de clicar no botão Ativar para mudar para a IU v1.1.

4. Na página Publicar API , clique no botão Criar credenciais da API . Este passo pode demorar alguns minutos a concluir.

   O ID de Cliente e uma nova chave de API são gerados automaticamente:

   

   As credenciais da API foram agora criadas; ativou ou renovou a API. Os seguintes itens são agora apresentados na página Publicar API :

   • O seu ID de Cliente.
   • Chaves de API.
     • A data de expiração para cada chave de API.

5. Anote o seguinte:

   • O ID de Cliente.
   • A nova chave de API.

   Irá utilizar o ID de Cliente e a chave de API no cabeçalho do pedido ao utilizar um ponto final REST.

v1

1. No programador do Centro de Parceiros dashboard, inicie sessão na conta que utilizou para publicar um suplemento.

2. No programa Microsoft Edge , selecione Publicar API.

3. Na página Publicar API , clique no botão Criar credenciais da API . Este passo pode demorar alguns minutos a concluir.

   As credenciais da API foram agora criadas; ativou ou renovou a API. Os seguintes itens são agora apresentados na página Publicar API :

   • O seu ID de Cliente.
   • O URL do token de acesso.
   • Segredos do cliente.
     • A data de expiração de cada Segredo.

   

4. Anote o seguinte:

   • O ID de Cliente.
   • O URL do token de acesso.
   • O novo segredo do Cliente.

   Irá utilizar o ID de Cliente, o URL do token de acesso e o segredo do cliente para obter um token de acesso, por Obter o token de acesso, abaixo de . Em seguida, irá utilizar o token de acesso no cabeçalho do pedido ao utilizar um ponto final REST.

Importante

Certifique-se de que anota o segredo do cliente agora, porque só está visível imediatamente após ativar ou renovar a API (ou seja, depois de criar as credenciais da API). Este segredo em particular não é apresentado novamente.

Pode gerar vários segredos de cliente para o ID de Cliente. Por exemplo, pode criar múltiplos segredos para vários projetos.

Obter o token de acesso

Obtém um token de acesso ao enviar uma mensagem POST para um URL de token de acesso. A IU do Centro de Parceiros mostra o URL do token de acesso, que é o mesmo que neste artigo. Em seguida, inclui o token de acesso no cabeçalho ao utilizar um ponto final de API, como o ponto final para Carregar um pacote para atualizar uma submissão existente, abaixo.

Descrição do ponto final a utilizar para obter um token de acesso:

Endpoint: https://login.microsoftonline.com/5c9eedce-81bc-42f3-8823-48ba6258b391/oauth2/v2.0/token
Type: POST
Header Parameters: Content-Type: application/x-www-form-urlencoded

Solicitação de amostra

Por exemplo, para obter um token de acesso, envie um pedido POST para o URL do token de acesso ao introduzir um curl comando na linha de comandos, da seguinte forma:

> curl \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id={$Client_ID}" \
-d "scope=https://api.addons.microsoftedge.microsoft.com/.default" \
-d "client_secret={$Client_Secret}" \
-d "grant_type=client_credentials" \
-v \
https://login.microsoftonline.com/5c9eedce-81bc-42f3-8823-48ba6258b391/oauth2/v2.0/token

Resposta de amostra

É-lhe devolvido um token de acesso, como:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}

Para obter mais informações, veja Obter um token no plataforma de identidade da Microsoft e o fluxo de credenciais de cliente OAuth 2.0.

Utilizar os pontos finais da API

A API REST de Atualização expõe pontos finais para:

• Carregar um pacote para atualizar uma submissão existente
• Verificar a status de um carregamento de pacote
• Publicar a submissão
• Verificar o status de publicação

Estes pontos finais são apresentados abaixo.

Para utilizar esta API REST de Atualização de Suplementos do Microsoft Edge, tem de ter o seguinte, por acima:

v1.1

Uma chave de API e um ID de Cliente.

v1

Um token de acesso.

A API está disponível na raiz https://api.addons.microsoftedge.microsoft.comdo ponto final .

Não existem pontos finais da API REST para:

• Criar um novo produto.
• Atualizar os metadados de um produto, como a descrição.

Para criar um novo produto ou atualizar os metadados de um produto, tem de utilizar o Centro de Parceiros da Microsoft.

Carregar um pacote para atualizar uma submissão existente

Utilize este ponto final da API REST para atualizar o pacote de um suplemento. Esta API carrega um pacote para atualizar uma submissão de rascunho existente de um produto de suplemento.

Veja também Carregar um pacote para atualizar uma submissão existente na Referência da API REST para atualizar os Suplementos do Microsoft Edge.

Descrição do ponto final

v1.1

Endpoint: /v1/products/$productID/submissions/draft/package
Type: POST
Header Parameters: Authorization: ApiKey $ApiKey; X-ClientID: $ClientID; Content-Type: application/zip
Body content: the package file to upload

v1

Endpoint: /v1/products/$productID/submissions/draft/package
Type: POST
Header Parameters: Authorization: Bearer $TOKEN; Content-Type: application/zip
Body content: the package file to upload

$productID é o ID de produto do Suplemento do Microsoft Edge que pretende atualizar.

Para obter o ID do produto:

1. Inicie sessão no programador do Centro de Parceiros dashboard.

2. Aceda aDescrição Geral doMicrosoft Edge>.

3. Selecione a extensão para a qual pretende obter o ID do produto.

   É aberta a página Descrição geral da extensão . O ID do produto é apresentado na página. (O ID do produto também é apresentado como o GUID no URL na Barra de endereço, entre microsoftedge/ e /packages.)

4. Na secção Identidade da extensão (ou a partir da Barra de endereço), selecione e copie o ID do Produto.

Solicitação de amostra

Para carregar um pacote para atualizar uma submissão existente, utilize o curl comando numa linha de comandos da seguinte forma:

v1.1

> curl \
-H "Authorization: ApiKey $ApiKey" \
-H "X-ClientID: $ClientID" \
-H "Content-Type: application/zip" \
-X POST \
-T $FILE_NAME \
-v \
https://api.addons.microsoftedge.microsoft.com/v1/products/$productID/submissions/draft/package

v1

> curl \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/zip" \
-X POST \
-T $FILE_NAME \
-v \
https://api.addons.microsoftedge.microsoft.com/v1/products/$productID/submissions/draft/package

Se o pedido for bem-sucedido e o processo de atualização começar, receberá uma 202 Accepted resposta status código com um Location cabeçalho. Este cabeçalho de localização contém o operationID necessário para verificar a status da operação de atualização.

Veja também:

• Carregue um pacote para atualizar uma submissão existente na Referência da API REST para atualizar os Suplementos do Microsoft Edge.

Verificar a status de um carregamento de pacote

Utilize esta API para marcar a status do carregamento de pacotes.

$operationID é o ID da operação que é devolvido no cabeçalho de resposta de Carregar um pacote para atualizar uma submissão existente ou Publicar a submissão.

Veja também Verificar o status de publicação na Referência da API REST para atualizar os Suplementos do Microsoft Edge.

Descrição do ponto final

v1.1

Endpoint: /v1/products/$productID/submissions/draft/package/operations/$operationID
Type: GET
Header Parameters: Authorization: ApiKey $ApiKey; X-ClientID: $ClientID

v1

Endpoint: /v1/products/$productID/submissions/draft/package/operations/$operationID
Type: GET
Header Parameters: Authorization: Bearer $TOKEN

Solicitação de amostra

Para marcar a status de um carregamento de pacote, utilize o curl comando na linha de comandos da seguinte forma:

v1.1

> curl \
-H "Authorization: ApiKey $ApiKey" \
-H "X-ClientID: $ClientID" \
-X GET \
-v \
https://api.addons.microsoftedge.microsoft.com/v1/products/$productID/submissions/draft/package/operations/$operationID

v1

> curl \
-H "Authorization: Bearer $TOKEN" \
-X GET \
-v \
https://api.addons.microsoftedge.microsoft.com/v1/products/$productID/submissions/draft/package/operations/$operationID

Veja também:

• Verifique a status de um carregamento de pacotes na Referência da API REST para atualizar os Suplementos do Microsoft Edge.

Publicar a submissão

Utilize esta API para publicar o rascunho atual do produto no site suplementos do Microsoft Edge.

Veja também Publicar a submissão do rascunho do produto na Referência da API REST para atualizar os Suplementos do Microsoft Edge.

Descrição do ponto final

v1.1

Endpoint: /v1/products/$productID/submissions
Type: POST
Header Parameters: Authorization: ApiKey $ApiKey; X-ClientID: $ClientID
Body content: Notes for certification, in JSON format

v1

Endpoint: /v1/products/$productID/submissions
Type: POST
Header Parameters: Authorization: Bearer $TOKEN
Body content: Notes for certification, in JSON format

Solicitação de amostra

Para publicar a submissão, utilize o curl comando na linha de comandos da seguinte forma:

v1.1

> curl \
-H "Authorization: ApiKey $ApiKey" \
-H "X-ClientID: $ClientID" \
-X POST \
-d '{ "notes"="text value" }' \
-v \
https://api.addons.microsoftedge.microsoft.com/v1/products/$productID/submissions

v1

> curl \
-H "Authorization: Bearer $TOKEN" \
-X POST \
-d '{ "notes"="text value" }' \
-v \
https://api.addons.microsoftedge.microsoft.com/v1/products/$productID/submissions

Se o pedido for bem-sucedido e o processo de publicação começar, receberá uma 202 Accepted resposta status código com um Location cabeçalho. Este cabeçalho de localização contém o operationID necessário para verificar a status da operação de publicação.

Veja também:

• Publique a submissão do rascunho do produto na Referência da API REST para atualizar os Suplementos do Microsoft Edge.

Verificar o status de publicação

Utilize esta API para marcar a status da operação de publicação.

$operationID é o ID da operação que é devolvido no cabeçalho de resposta de Carregar um pacote para atualizar uma submissão existente ou Publicar a submissão.

Veja também Verificar o status de publicação na Referência da API REST para atualizar os Suplementos do Microsoft Edge.

Descrição do ponto final

v1.1

Endpoint: /v1/products/$productID/submissions/operations/$operationID
Type: GET
Header Parameters: Authorization: ApiKey $ApiKey; X-ClientID: $ClientID

v1

Endpoint: /v1/products/$productID/submissions/operations/$operationID
Type: GET
Header Parameters: Authorization: Bearer $TOKEN

Solicitação de amostra

Para marcar a status de publicação, utilize o curl comando na linha de comandos da seguinte forma:

v1.1

> curl \
-H "Authorization: ApiKey $ApiKey" \
-H "X-ClientID: $ClientID" \
-X GET \
-v \
https://api.addons.microsoftedge.microsoft.com/v1/products/$productID/submissions/operations/$operationID

v1

> curl \
-H "Authorization: Bearer $TOKEN" \
-X GET \
-v \
https://api.addons.microsoftedge.microsoft.com/v1/products/$productID/submissions/operations/$operationID

Veja também:

• Verifique o status de publicação na Referência da API REST para atualizar os Suplementos do Microsoft Edge.

Confira também

• Referência da API REST para atualizar os Suplementos do Microsoft Edge – API REST para atualizar uma extensão.
• APIs suportadas para extensões do Microsoft Edge – APIs JavaScript para desenvolver uma extensão.

GitHub:

• Problemas no edge-developer repositório para documentos para Programadores do Microsoft Edge.

plataforma de identidade da Microsoft:

• plataforma de identidade da Microsoft e o fluxo de credenciais de cliente OAuth 2.0