Skip to main content

Visão geral da API

Importante

Caso não tenha experiência com APIs, visite a página de ajuda Introdução às APIs .

Importante

A partir da versão 22.1, os pontos de extremidade de API OAuth1 públicos herdados foram removidos porque exigem hash SHA1 não compatível com FIPS. Essa remoção inclui os pontos de extremidade WCF (Windows Communication Framework) herdados, o Swagger para esses pontos de extremidade herdados e o middleware de OAuth1. Para substituir os pontos de extremidade OAuth1, você pode usar as versões OAuth2 das APIs herdadas lançadas na versão 21.4, que são compatíveis com FIPS. As APIs OAuth2 oferecem a mesma experiência de funcionalidade das APIs OAuth1.

Os pontos de extremidade V1 e V2 e de assinatura continuarão sendo compatíveis no OAuth2.

Para saber mais sobre a conversão e seus impactos, acesse a página de ajuda Instruções para conversão de OAuth1 para OAuth2 ou este artigo .

A API do Server é composta por cinco APIs:

  • API de assinatura : pontos de extremidade para que os usuários interajam com assinaturas, fluxos de trabalho e agendamentos (trabalhos).

  • API V2 de usuário : pontos de extremidade para que os usuários interajam com credenciais, arquivos de entrada e agendamentos (trabalhos).

  • API V1 de administrador : pontos de extremidade para que os administradores busquem recursos da interface do administrador.

  • API V2 de administrador : versão 2 dos pontos de extremidade para que os administradores busquem recursos da interface do administrador.

  • API V3 de administrador : versão 3 dos pontos de extremidade. Esta versão usa OAuth 2.

Nota

Além de adicionar novas funcionalidades com pontos de extremidade de API V3 , também disponibilizamos nossos pontos de extremidade V1, de assinatura e pontos de extremidade V2 para uso com OAuth 2. Os mesmos pontos de extremidade que você usou anteriormente agora estão disponíveis para OAuth 2 em um novo endereço base.

O endereço da API Web pode ser configurado apenas para V1, V2 e V3 usando o OAuth 2. Para a documentação da API V1 e V2 usando o OAuth 1, o endereço é http://{ServerHostname}/gallery/api-docs/ .

The Web API address can be set up in System Settings.

Acessar a documentação de referência da API do Server

A documentação de referência completa para todos os pontos de extremidade de API do Server está disponível no Swagger.

Há dois locais na IU do Server onde você pode acessar a documentação de referência da API do Server.

  1. Clique no ícone de ponto de interrogação na barra de ferramentas superior e selecione  Documentação da API .

    Thumbnail

  2. Selecione seu nome de usuário e selecione  Meu perfil  >  Chaves . Você pode encontrar links para a documentação da API ao lado das chaves da API.

Você também pode acessar a documentação de referência da API para a API do Server usando este URL: http(s)://serverhostname.domain/webapi/swagger

Autenticação na documentação de referência da API do Server

Os documentos da API do Server são interativos, permitindo que você preencha os parâmetros e veja as respostas. Para usar a interatividade, você precisa fazer a autenticação. Para isso, siga estas etapas:

  1. Na IU do Server, selecione seu nome de usuário e vá para Meu perfil > Chaves . Copie as chaves de API para a API na qual deseja se autenticar e cole-as nos campos API Key  (chave de API) e Shared Secret (segredo compartilhado). As chaves serão salvas e exibidas como Saved .

  2. Selecione a chamada que deseja executar, preencha os parâmetros e clique em Try it out! para testar.

Chaves de API e acesso à API

Os administradores do Server precisam permitir que os usuários acessem a API. Acesse Permitir acesso de usuários à API do Server para obter mais informações. Depois que você tiver concedido aos usuários acesso à API, eles poderão encontrar suas chaves de API na guia Chaves da página Meu perfil . Para acessar suas chaves de API, selecione seu nome de usuário e vá para Meu perfil > Chaves .

API keys are located under My Profile Keys.

Os usuários com a função de administrador podem usar as chaves de Acesso à API para acessar todas as APIs, incluindo a API de assinatura, a API V2 de usuário, a API V1 de administrador, a API V2 de administrador e a API V3.

Todos os usuários que não sejam administradores podem usar as chaves de Acesso à API para acessar a API de assinatura e a API V2 de usuário.

Todos os usuários podem usar as chaves da API do Private Studio para acessar a API de assinatura.

Criar pontos de extremidade de API

Para construir um ponto de extremidade de API, use este esquema: <hostname>/webapi/

Autenticação

Consulte o artigo  Configuração e autorização da API do Server .

Pontos de extremidade de API e parâmetros

Nesta seção, você encontrará mais informações sobre os seguintes pontos de extremidade:

Ponto de extremidade Auditlog

O Server monitora as alterações feitas nas seguintes entidades do sistema:

  • AppInfo (fluxo de trabalho)

  • Coleção

  • Credencial

  • Assinatura

  • Usuário

  • Grupo de usuário

Obter eventos registrados pela API do Server

Qualquer atualização feita nessas entidades aciona a criação de um registro AuditEvent (evento de auditoria). Você pode fazer o retorno desses registros por meio de um ponto de extremidade público de API de administrador.

Ponto de extremidade

O ponto de extremidade para AuditEvents é GET /admin/v1/auditlog/

Parâmetros de consulta obrigatórios

  • entity : (string) a entidade do log de auditoria a ser consultada.

  • page : (int) a página a ser retornada.

  • pageSize : (int) o número de registros a serem retornados em cada página.

A resposta será uma série de registros de evento de auditoria:

[
  {
    "id": "",
    "entity": "",
    "entityId": "",
    "userId": "",
    "timestamp": "Date",
    "event": "",
    "oldValues": "",
    "newValues": ""
  }
]

As propriedades retornadas estão definidas abaixo:

  • id : o ID do evento de auditoria.

  • entity : o nome da entidade.

  • entityId : o ID da entidade.

  • userId : o ID do usuário que modificou a entidade.

  • timestamp : a data/hora de criação do registro do evento de auditoria.

  • event : o evento que ocorreu (inserção, atualização, exclusão).

  • oldValues : os valores das propriedades antes da atualização.

  • newValues : os valores das propriedades depois da atualização.

Ponto de extremidade Inputfiles

Para executar fluxos de trabalho que usam a ferramenta Explorador de Arquivos por meio da API, use o ponto de extremidade /user/v2/inputfiles para fazer upload do arquivo.File Browse Tool Icon Ferramenta Explorador de Arquivos

  1. Comece fazendo uma solicitação POST multipart/form-data para o ponto de extremidade /user/v2/inputfiles para publicar um arquivo temporário. O nome da seção form-data obrigatória é InputFile .

    curl --location --request POST 'http:{yourhostname}/api/user/v2/inputfiles/' \
--form 'inputFile=@/file/path/filename.csv'

  2. Em seguida, faça um POST para o ponto de extremidade /user/v2/workflows/{appId}/jobs/ .

    1. Em seguida, inclua o nome ( name ) da ferramenta Explorador de Arquivos no objeto de pergunta. Se você não tiver certeza do nome da ferramenta Explorador de Arquivos, use o ponto de extremidade /v1/workflows/{appId}/questions para obtê-lo.

    2. O value é o ID de referência que a chamada do arquivo de entrada retornou na resposta.

    curl --location --request POST 'http:{yourhostname}/api/user/v2/workflows/{appId}/jobs' \
--header 'Content-Type: text/plain' \
--header 'Authorization: OAuth oauth_consumer_key="{consumer key}",
                         oauth_signature_method="HMAC-SHA1",
                         oauth_timestamp="{timestamp}",
                         oauth_nonce="{nonce}",
                         oauth_signature="{signature}"' \
--data-raw '{
    "questions": [
        {
            "name": "File Browse",
            "value": "{reference ID}"
        }
    ]
    "priority": "Low"
}'

Ponto de extremidade migrável

Use o ponto de extremidade migratable para migrar fluxos de trabalho entre ambientes do Server. Você pode usar isso para gerenciar implantações de fluxo de trabalho durante as fases de desenvolvimento e teste.

Para começar, você precisa habilitar fluxos de trabalho para migração . Depois de marcar fluxos de trabalho para migração, siga estas etapas para publicá-los do ambiente de origem na assinatura apropriada (estúdio) de um ambiente de destino.

Etapa 1. Obter uma lista de fluxos de trabalho prontos para migração

Em seguida, obtenha uma lista de fluxos de trabalho prontos para migrar usando o seguinte ponto de extremidade:

  • Ambiente: origem

  • Método: GET

  • Ponto de extremidade: api/admin/v1/workflows/migratable/?subscriptionIds={subscriptionIds}/

Inclua uma lista separada por vírgulas de subscriptionIds  (IDs de assinatura) como um parâmetro de consulta. Os IDs de assinatura identificam um estúdio específico.

O retorno é uma variedade de fluxos de trabalho marcados como prontos para a migração dentro da assinatura especificada (estúdio). Se você não fornecer subscriptionsIds , o retorno incluirá todos os fluxos de trabalho marcados como prontos para migração. O retorno inclui três propriedades: appId  (o ID do aplicativo),  revisionId  (a revisão atualmente publicada) e subscriptionID  (o ID da assinatura à qual o fluxo de trabalho pertence).

Etapa 2. Fazer download dos fluxos de trabalho do ambiente de origem

O ponto de extremidade a seguir baixa o fluxo de trabalho como um arquivo YXZP.

  • Ambiente: origem

  • Método: GET

  • Ponto de extremidade: api/admin/v1/{appID}/package/

Inclua um appID como um parâmetro de caminho. O retorno será um download de todo o fluxo de trabalho como um pacote.

Etapa 3. Publicar fluxos de trabalho no ambiente de destino

O ponto de extremidade a seguir publica o fluxo de trabalho baixado no ambiente de destino.

  • Ambiente: destino

  • Método: POST

  • Ponto de extremidade: api/admin/v1/workflows/

Parâmetros

Parâmetro

Descrição

Tipo

Obrigatório

file

O nome do arquivo do novo fluxo de trabalho.

Cadeia de caracteres

Verdadeiro

name

O novo nome do fluxo de trabalho.

Cadeia de caracteres

Verdadeiro

owner

O proprietário do fluxo de trabalho migrado. O endereço de e-mail deve existir no ambiente de destino.

Cadeia de caracteres

Verdadeiro

validate

Sinalizador para validar o fluxo de trabalho ao migrar para o ambiente de destino.

Booleano

Verdadeiro

isPublic

Sinalizador para definir o fluxo de trabalho como público para ser exibido no "Server da minha empresa" no ambiente de destino.

Booleano

Verdadeiro

sourceId

Este é o appId do ambiente de origem do fluxo de trabalho a ser migrado. Se existir um fluxo de trabalho com o mesmo sourceId, ele será substituído no ambiente de destino. Caso contrário, um novo fluxo de trabalho será gerado.

(Envie uma string vazia se não desejar especificar um appID.)

Cadeia de caracteres

Verdadeiro

workerTag

Adicione ao fluxo de trabalho uma tag de trabalhador para que um trabalhador específico execute o fluxo.

(Envie uma string vazia se não quiser especificar o trabalhador.)

Cadeia de caracteres

Verdadeiro

canDownload

Sinalizador para definir o fluxo de trabalho como disponível para download por outros usuários no ambiente de destino.

Booleano

Verdadeiro

(Opcional) Etapa 4. Redefinir configuração de migração de fluxos de trabalho no ambiente de origem

Se desejar, você pode usar o ponto de extremidade migratable para alternar a configuração Este fluxo de trabalho está pronto para ser migrado em um fluxo de trabalho de volta para Não no ambiente de origem após a migração do fluxo de trabalho no ambiente de destino.

  • Ambiente: origem

  • Método: PUT

  • Ponto de extremidade: api/admin/v1/workflows/migratable/{appID}/

Para obter mais informações sobre os pontos de extremidade de API V3 do Server e seus parâmetros, acesse a página de ajuda API V3 do Alteryx Server .

Nesta secção: